---
title: "Site Management 🧰"
date: "2023-06-24T16:10:29+03:00"
author: "anybody"
draft: false 
keywords:
  - internal
  - journal management
abstract: |
  (Internal) Technical guide for site management. 
---

[Obsidian]: https://obsidian.md/ "Obsidian is a free-to-use cross-platform Markdown editor aimed at note-taking."
[VS Code]: https://code.visualstudio.com/ "Visual Studio Code (VS Code) is an open-source source-code editor for Windows, macOS, and Linux, developed by Microsoft."
[Sourcetree]: https://www.sourcetreeapp.com/ "Sourcetree is a free-to-use Git GUI for Windows and macOS."
[iTerm2]: https://iterm2.com/ "iTerm2 is a free and open source CLI Terminal for macOS."
[Go language]: https://go.dev/ "Go is an open-source multi-paradigm object-oriented programming language."
[Git]: https://git-scm.com/ "Git is a free and open-source distributed version control system."
[Hugo]: https://gohugo.io/ "Free and open-source static website builder."
[Hugo installation guide]: https://gohugo.io/installation/

[Calibre]: https://calibre-ebook.com/ "Calibre-ebook.com; free, open source and cross-platform eBook management software."
[Accorder]: https://pypi.org/project/accorder/ "Accorder at pypi.org; Command line tool for rendering  "
[Zotero]: https://www.zotero.org/ "Zotero.org; free, open source and cross-platform citation management software."


# Introduction 

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

There are two main ways to manage and edit this site: 
1. **On a browser via the preview site** (only for content management; see [management via online preview site](#preview-site)). 
2. **Via a local clone of the site repository** (recommended, especially for major changes; see [Site management via local repository clone](#local-repo)). 

Notes: 
- Both workflows require write access to the project repository.
- For new content specifically see instructions at  ![Content Management](issue:int-issue-content-management).

# Content management via online preview site {#preview-site}


Note: for an extended guide for content management see ![Content Management](issue:int-issue-content-management).

To access the online preview site append `/_preview/` to the [sitemap](/) URL. 

## 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](/internal/sandpoints-online-interface.png)


|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 | 
<figcaption>Table 1: Sandpoints online preview site edit options explained.</figcaption>

*Note: Any action requires the user to be logged in to the project repository.*
## 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).](/internal/sandpoints-online-edit.png)

## 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. 
# Site management via local repository clone {#local-repo}

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. 
## Required tools and installations

To manage the site you first need to install: 
1. [Git][] -- version control system. 
2. [Hugo][] -- a static website builder ([see instructions below](#get-hugo)).
3. It's recommended to install the [Go Language][].

To manage the site you need the following tools: 
1. a Markdown editor (e.g. [Obsidian][]), or a code editor (e.g. [VS Code][]) or other general text editor to view and edit Markdown files. For *Obsidian*, open the `content` folder as a vault. 
2. 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 [iTerm2][].
3. a [Git][] management tool. Experienced Git users can use a terminal. An easier workflow is to use a GUI Git software (e.g. [Sourcetree][]), or the Git integration of [VS Code][]. 

## Installing and upgrading Hugo {#get-hugo}

To install [Hugo][] for your system see [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 
```
## 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`). 

## Editing the site

To edit the site it's recommended use a Markdown or other text editor such as [Obsidian][] or [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-content), ![naming and other conventions](article:int-conventions), and ![Markdown formatting](article:md-formatting).

## Committing changes 

If inexperienced with [Git][], use a GUI tool like [Sourcetree][], that can visualize commits, and branches of the repository, and display file version differences between commits. 
## 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
```
## 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.
## Building the site locally 

Hugo has three main ways of compiling/building a site:  
1. **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](#localhost-server).
2. **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 [FileZilla][]). See [Compile site locally via Hugo](#build). 
3. **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](#offline). 

[FileZilla]: https://filezilla-project.org/ "Free and open-source cross-platform FTP software."

### Create a local HTTP server {#local-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. 

### Compile site locally via Hugo {#build}

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).*  
### Compile portable offline version of the site {#offline}

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/`.

# Debugging 

For debugging see ![How to break or debug this site](article:int-break). 

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