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 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, and collaboration/version control is managed via [Git][].
|
||||
Thus, with the infrastructure in place, no programming is needed
|
||||
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.
|
||||
|
||||
# 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:
|
||||
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:
|
||||
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 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
|
||||
Library management requires Calibre, Accorder, and Zotero. For detailed instructions see .
|
||||
|
||||
## Install and upgrade Hugo {#get-hugo}
|
||||
## 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.
|
||||
|
||||
|
|
@ -58,8 +113,7 @@ To check the version of your _Hugo_ installation, do:
|
|||
```
|
||||
hugo version
|
||||
```
|
||||
|
||||
# Cloning the site
|
||||
## 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`
|
||||
|
||||
|
|
@ -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`).
|
||||
|
||||
# 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 .
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
<!--
|
||||
# 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:
|
||||
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 the site
|
||||
## Building/compiling the online site
|
||||
|
||||
Hugo has two main ways of compiling/building a website:
|
||||
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.
|
||||
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][]).
|
||||
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
|
||||
### 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:
|
||||
- To create a local server accessible via a browser, that follows real-time changes to your repo clone, do:
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Compile a static website
|
||||
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:
|
||||
Additional options for this command are:
|
||||
- `--navigateToChanged` -> automatically navigate to a page that is being edited.
|
||||
- `--noHTTPCache` -> prevent HTTP caching.
|
||||
|
||||
- To build the website (in the folder `/public/`), do:
|
||||
```
|
||||
hugo
|
||||
```
|
||||
- To build the website including all drafts (also in the folder `/public/`), do:
|
||||
```
|
||||
hugo -D
|
||||
```
|
||||
### Compile site locally via Hugo {#build}
|
||||
|
||||
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:
|
||||
```
|
||||
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, 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