197 lines
No EOL
10 KiB
Markdown
197 lines
No EOL
10 KiB
Markdown
---
|
|
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 ).
|
|
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)).
|
|
|
|
*Note: Both workflows require write access to the project repository*.
|
|
|
|
<!--Library management requires [Calibre][], [Accorder][], and [Zotero][]. -->
|
|
|
|
|
|
# Content management via online preview site {#preview-site}
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|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.*
|
|
- For creating new content via the preview site see instructions at .
|
|
|
|
## 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`.
|
|
|
|
|
|
|
|
## 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 , , and .
|
|
|
|
## 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 .
|
|
|
|
*Note: If the site does not update after a `publish` command, there is likely an error that prevents the server from rebuilding the site.* |