[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."
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)).
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).
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][].
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:
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`).
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 .
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.
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.
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).
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 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.
