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 and git 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) Consider hugo 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 than brew, 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)

Markdown editors can be configured to automatically use this configuration:

Typora

Atom