Hugo is a static site generator platform, see https://gohugo.io/ It’s very, very fast, very easy to use, and the simplest to get started (I think).
Quickstart:
git clone <this repository>
git submodule init
andgit submodule update --recursive --remote
to update local copy of academic theme.brew install hugo
Running the site locally:
hugo serve
to preview the site locally on http://localhost:1313/ (Ctrl+c
to stop) Considerhugo serve --disableFastRender --disableLiveReload --gc
in case you’re having caching issues.- Push
master
to trigger build/deploy (there is currently only a production environment)
Creating Content:
hugo new post/<long-name-of-post>/
e.g.hugo new post/configuring-the-perfect-terminal-experience-in-osx/
which creates an_index.md
within that directory under “posts” with a preconfigured page, ready to accept content.
Upgrading Hugo:
brew upgrade hugo
(or, if you used a method other thanbrew
, see the Hugo docs)- To upgrade Academic itself,
Reference https://sourcethemes.com/academic/docs/managing-content/ for list of available fields, tips, etc.
Categories and Tags
What are Categories vs Tags? Generally speaking there should be one Category and several Tags (as needed). In practice they are both just Hugo taxonomies, so functionally identical, but the Academic theme uses them as follows:
- Tags - are rendered as “Topics” in the word cloud on the homepage. They render as links at the bottoms of individual posts, which point to listing pages of shared tags, e.g.
/tags/bash/
- Categories - make it possible to filter for a list of posts based on this, e.g.
/categories/bash/
. Categories are displayed on the posts as clickable links, including in the previews (on the homepage).
Example (to be put in the front matter), add ---
for clarity:
---
categories: ['OSX']
tags: ['OSX Tweaking','TEST']
---
Academic Theme
From https://sourcethemes.com/academic/ and https://github.com/gcushen/hugo-academic
Handling Images
Handling image the way Academic Theme expects:
/post/long-name-of-post-used-in-titles/index.md
- Images should go in
./assets
- Use relative links, e.g.
![](assets/my-image.png)
- Images should go in
Markdown editors can be configured to automatically use this configuration: