jgdr/content/article/int-management.md

---
title: "Site Management 🧰"
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 instructions below](#get-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 ![Library management](article:int-library). 

## 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 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 ![content creation](article:int-content), ![naming and other conventions](article:int-conventions), and ![Markdown formatting](article:markdown-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. 


<!--
# 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
   ```