added instructions for Online Editing + via Local clone
This commit is contained in:
parent
d62c2c93b1
commit
a33b891a2b
1 changed files with 100 additions and 33 deletions
|
|
@ -19,14 +19,72 @@ abstract: |
|
||||||
[Hugo]: https://gohugo.io/ "Free and open-source static website builder."
|
[Hugo]: https://gohugo.io/ "Free and open-source static website builder."
|
||||||
[Hugo installation guide]: https://gohugo.io/installation/
|
[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
|
# Introduction
|
||||||
|
|
||||||
This project runs on *Sandpoints*, a module/theme for the static website builder [Hugo][].
|
This project runs on *Sandpoints*, a module/theme for the static website builder [Hugo][].
|
||||||
Content is organized with plain-text Markdown files, and collaboration/version control is managed via [Git][].
|
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 ).
|
||||||
Thus, with the infrastructure in place, no programming is needed
|
With the infrastructure in place, no programming is needed to maintain this project.
|
||||||
|
|
||||||
# Required tools and installations
|
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, testing, and committing edits to multiple files concurrently (rather than editing entries individually).
|
||||||
|
- Having a local copy of all modifications before they are committed.
|
||||||
|
- Making edits using a Markdown editor, rather than a Git textbox.
|
||||||
|
## Required tools and installations
|
||||||
|
|
||||||
To manage the site you first need to install:
|
To manage the site you first need to install:
|
||||||
1. [Git][] -- version control system.
|
1. [Git][] -- version control system.
|
||||||
|
|
@ -36,12 +94,9 @@ To manage the site you first need to install:
|
||||||
To manage the site you need the following tools:
|
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.
|
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][].
|
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 would be to use a GUI git software (e.g. [Sourcetree][]), or the Git integration of [VS Code][].
|
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][].
|
||||||
|
|
||||||
## Library management tools
|
## Installing and upgrading Hugo {#get-hugo}
|
||||||
Library management requires Calibre, Accorder, and Zotero. For detailed instructions see .
|
|
||||||
|
|
||||||
## Install and upgrade 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 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.
|
||||||
|
|
||||||
|
|
@ -58,8 +113,7 @@ To check the version of your _Hugo_ installation, do:
|
||||||
```
|
```
|
||||||
hugo version
|
hugo version
|
||||||
```
|
```
|
||||||
|
## Cloning the site repository
|
||||||
# Cloning the site
|
|
||||||
|
|
||||||
Assuming you have access to the project repository, which should have a URL in the form of `https://github.com/fake-repo/repo.git`
|
Assuming you have access to the project repository, which should have a URL in the form of `https://github.com/fake-repo/repo.git`
|
||||||
|
|
||||||
|
|
@ -70,52 +124,65 @@ 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`).
|
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
|
## 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 .
|
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
|
## 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.
|
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:
|
||||||
<!--
|
|
||||||
# Install or upgrade Sandpoints
|
|
||||||
|
|
||||||
To install or update _Sandpoints_, navigate to the root folder of the project and run the following two commands, one at a time:
|
|
||||||
```
|
```
|
||||||
hugo mod get
|
hugo mod get
|
||||||
hugo mod vendor
|
hugo mod vendor
|
||||||
```
|
```
|
||||||
-->
|
## Building/compiling the online site
|
||||||
# Building the site
|
|
||||||
|
|
||||||
Hugo has two main ways of compiling/building a website:
|
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.
|
||||||
1. Create a local real-time HTML server. This makes the site accessible locally via a browser on a URL like `http://localhost:1313/`. This is useful for testing, or for performing and viewing various edits locally before such changes are made public, especially because the site is updated in real-time against changes made in its content.
|
## Building the site locally
|
||||||
2. Compile a static HTML version of the site. The compiled site will be placed inside the folder `repo/public/`. The contents of this folder can be uploaded to a server (e.g. via [FileZilla][]).
|
|
||||||
|
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."
|
[FileZilla]: https://filezilla-project.org/ "Free and open-source cross-platform FTP software."
|
||||||
|
|
||||||
## Create a local HTTP server
|
### Create a local HTTP server {#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 one of the following:
|
Navigate to the root folder of the cloned repository (by the previous example that would be `cd c:/users/me/repo/`), and do one of the following:
|
||||||
- To create a local server accessible via a browser, that follows real-time changes to your repo clone, do:
|
- To create a local server accessible via a browser, that follows real-time changes to your repo clone, do:
|
||||||
```
|
```
|
||||||
hugo server
|
hugo server
|
||||||
```
|
```
|
||||||
- To do the same as before, but include all draft content, do:
|
- To do the same *including all draft content*, do:
|
||||||
```
|
```
|
||||||
hugo server -D
|
hugo server -D
|
||||||
```
|
```
|
||||||
|
|
||||||
## Compile a static website
|
Additional options for this command are:
|
||||||
Navigate to the root folder of the cloned repository (by the previous example that would be `cd c:/users/me/repo/`), and do one of the following:
|
- `--navigateToChanged` -> automatically navigate to a page that is being edited.
|
||||||
|
- `--noHTTPCache` -> prevent HTTP caching.
|
||||||
|
|
||||||
- To build the website (in the folder `/public/`), do:
|
### Compile site locally via Hugo {#build}
|
||||||
```
|
|
||||||
hugo
|
Compiling the site locally via Hugo requires a local clone of the repository. 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:
|
||||||
```
|
```
|
||||||
- To build the website including all drafts (also in the folder `/public/`), do:
|
hugo
|
||||||
```
|
```
|
||||||
hugo -D
|
|
||||||
```
|
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, that can be copied and run on USB sticks (for example).
|
||||||
|
To render an offline portable version, do:
|
||||||
|
```
|
||||||
|
hugo -e offline
|
||||||
|
```
|
||||||
|
|
||||||
|
This will also compile the site at `/public/`.
|
||||||
Loading…
Add table
Reference in a new issue