From a33b891a2b7b79fce02ab80e92a9bbf24fd559ea Mon Sep 17 00:00:00 2001 From: constantinos Date: Mon, 14 Aug 2023 16:46:55 +0300 Subject: [PATCH] added instructions for Online Editing + via Local clone --- content/article/int-management.md | 133 ++++++++++++++++++++++-------- 1 file changed, 100 insertions(+), 33 deletions(-) diff --git a/content/article/int-management.md b/content/article/int-management.md index e7c62c1..4908b72 100644 --- a/content/article/int-management.md +++ b/content/article/int-management.md @@ -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 ![Library management](article:int-library)). +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*. + + + + +# 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. + +![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 | +
Table 1: Sandpoints online preview site edit options explained.
+ +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 ![Content creation instructions](issue:int-archetypes). + +## 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, 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 ![Library management](article:int-library). - -## 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 ![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 - - -# 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/`. \ No newline at end of file