121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
---
|
|
title: "Site Management (INTERNAL)"
|
|
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/
|
|
|
|
|
|
# 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
|
|
|
|
# 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 instruction below](#install-and-upgrade-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 would be 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
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
|
<!--
|
|
# 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 vendor
|
|
```
|
|
-->
|
|
# Building the 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][]).
|
|
|
|
[FileZilla]: https://filezilla-project.org/ "Free and open-source cross-platform FTP software."
|
|
|
|
## Create a local HTTP 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:
|
|
```
|
|
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:
|
|
|
|
- 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
|
|
```
|