Site Management 🧰

1. Introduction¶

This project runs on Sandpoints, a module/theme for the static website builder www⁄Hugo. Content is organized with plain-text Markdown files. Collaboration/version control is managed via www⁄Git. The library is setup using www⁄Calibre and www⁄Accorder (for detailed instructions see article⁄Library management). With the infrastructure in place, no programming is needed to maintain this project.

There are two main ways to manage and edit this site:

On a browser via the preview site (only for content management; see §⁄management via online preview site).
Via a local clone of the site repository (recommended, especially for major changes; see §⁄Site management via local repository clone).

Notes:

Both workflows require write access to the project repository.
For new content specifically see instructions at issue⁄Content Management.

2. Content management via online preview site¶

Note: for an extended guide for content management see issue⁄Content Management.

To access the online preview site append /_preview/ to the ⁄sitemap URL.

2.1. Preview site interface¶

The preview site enables a toolbar with five options (Screenshot 1), outlined in Table 1.

Screenshot 1: Interface of online preview site

Preview site options
EDIT_THIS	edit the current page
ADD_JOURNAL / ADD_ISSUE / ADD_ARTICLE	create new entry by type
PUBLISH	recompile the website and include all unpublished changes
?	open the repository website

Table 1: Sandpoints online preview site edit options explained.

Note: Any action requires the user to be logged in to the project repository.

2.2. Edit existing entries via the preview site¶

All modifications (edits or new items) are carried out as Git commits (Screenshot 2). To edit an existing entry navigate to the entry and click EDIT_THIS from the preview site interface. After finishing all necessary edits, add a commit message, and press Commit changes.

Screenshot 2: Sandpoints preview site; interface for editing entries (EDIT_THIS).

2.3. Recompile and publish the site¶

To recompile the site and include any unpublished changes, either:

include the keyword !publish! in a commit message, or
click the button Publish of the preview website toolbar.

3. Site management via local repository clone¶

Making changes via a local clone of the site repository is recommended especially for larger scale edits, modifications of the site as well as for testing purposes. However, it has a slightly higher overhead and requires installing some software. The key benefits of making edits on a repository clone, over the preview page include:

Running a localhost server for previewing changes (before they are committed).
Making, and committing edits to multiple files concurrently (rather than editing entries individually).
Having a local copy of all modifications before they are committed.
Working with unpublished (draft) material.
Making edits using a Markdown editor, rather than a Git textbox.
Making non-destructive tests end edits.
Making and testing theme modifications.

3.1. Required tools and installations¶

To manage the site you first need to install:

www⁄Git – version control system.
www⁄Hugo – a static website builder (§⁄see instructions below).
It’s recommended to install the www⁄Go Language.

To manage the site you need the following tools:

a Markdown editor (e.g. www⁄Obsidian), or a code editor (e.g. www⁄VS Code) or other general text editor to view and edit Markdown files. For Obsidian, open the content folder as a vault.
a command line interface (CLI) terminal. Windows users can use PowerShell or Git Bash (included with a Git installation). macOS users can use the default Terminal app, or www⁄iTerm2.
a www⁄Git management tool. Experienced Git users can use a terminal. An easier workflow is to use a GUI Git software (e.g. www⁄Sourcetree), or the Git integration of www⁄VS Code.

3.2. Installing and upgrading Hugo¶

To install www⁄Hugo for your system see www⁄Hugo installation guide – Hugo is installed via a package manager, e.g. Homebrew for macOS or choco for Windows.

To upgrade Hugo:

For Windows, if Hugo was installed with the choco package manager, open a terminal as administrator and do:
```
choco upgrade hugo
```
For macOS, if Hugo was installed with the homebrew package manager, open a terminal and do:
```
brew upgrade hugo
```

To check the version of your Hugo installation, do:

hugo version

3.3. Cloning the site repository¶

Assuming you have access to the project repository, which should have a URL in the form of https://github.com/fake-repo/repo.git

Using a terminal, go to a folder where you want to clone the repository (e.g. c:/users/me/ for Windows), and do:

git clone https://github.com/fake-repo/repo.git

This will download a copy of all the material of the repository placed inside a folder with the name of the repository (in this example c:/users/me/repo).

3.4. Editing the site¶

To edit the site it’s recommended use a Markdown or other text editor such as www⁄Obsidian or www⁄VS Code. Editing only entails working with Markdown files within the /content/ folder of the project. See also the guides about content creation⦚article:int-contentnot found, article⁄naming and other conventions, and article⁄Markdown formatting.

3.5. Committing changes¶

If inexperienced with www⁄Git, use a GUI tool like www⁄Sourcetree, that can visualize commits, and branches of the repository, and display file version differences between commits.

3.6. Upgrading the Sandpoints theme¶

To upgrade the Sandpoints theme, navigate to the root folder of the project and run the following two commands, one at a time:

hugo mod get
hugo mod vendor

3.7. Building/compiling the online site¶

This site is automatically recompiled and updated by the server via Git commits. All commits that include the keyword !publish! will force the server to recompile the site taking into account the latest updates.

3.8. Building the site locally¶

Hugo has three main ways of compiling/building a site:

Create a local real-time HTML server. This runs the site on a localhost server, that is accessible via browser on a URL like http://localhost:1313/. This is useful for testing, for performing and viewing various edits locally, before changes are made public. This, especially because the localhost site is updated in real-time against changes made in its content. Also, because it allows previewing and editing unpublished (draft) content. See §⁄Create a local HTTP server.
Compile a static HTML version of the site. The compiled site will be placed inside the directory /public/. The contents of this directory can be uploaded to a server (e.g. via www⁄FileZilla). See §⁄Compile site locally via Hugo.
Compile a portable and offline version of the site. This version of the site can be run and copied via a USB stick (for example). See §⁄Compile portable offline version.

3.8.1. Create a local HTTP server¶

Hugo allows running a localhost server which updates in real-time to follow any changes. To run a local server, navigate to the root folder of the cloned repository (by the previous example that would be cd c:/users/me/repo/), and do:

hugo server

To include all draft content in the localhost server, do:

hugo server -D

Hugo will start a local server (by default this is at http://localhost:1313/). The server will update with any change made to Markdown entries of the site, or to the theme.

Additional options for this command are:

--navigateToChanged -> automatically navigate to a page that is being edited.
--noHTTPCache -> prevent HTTP caching.

3.8.2. Compile site locally via Hugo¶

Navigate to the root folder of the cloned repository via the terminal (by the previous example that would be cd c:/users/me/repo/), and do:

hugo

This will create (or overwrite) a directory named /public/ inside the root directory of the project. The contents of /public/ can be uploaded to a file server (e.g. via FileZilla).

Note: To compile the site including draft content do: hugo -D (do not upload this version).

3.8.3. Compile portable offline version of the site¶

Hugo allows compiling portable versions of the site which can be copied and run on a USB stick (for example). To render an offline portable version of the site, do:

hugo -e offline

This will also output the compiled site at /public/.

4. Debugging¶

For debugging see article⁄How to break or debug this site.

Note: If the site does not update after a publish command, there is likely an error that prevents the server from rebuilding the site.