Tome of Finite Knowledge

Hugo *actually getting started*

3 min read

The Hugo getting-started docs are awful and assume you do nothing but think and dream about the word “theme.” Theme theme theme Theme, theme theme theme, theme theme. Theme theme theme theme!

See also

These notes are built on top of this guy’s page, who is equally as frustrated about — theme theme theme theme theme theme — as I am: https://www.brycewray.com/posts/2022/07/really-getting-started-hugo/

I’m not even going to bother linking to the real Hugo docs (at least, not yet), because it did nothing but confuse me more.

I will, however, assume you can install Hugo. On Gentoo, simply sudo emerge -a www-apps/hugo (from the mim repo).

Step 1 - project creation

First, you’ll need a project directory.

$ hugo new site <project name>

Note that Hugo will create a new folder named <project name>; unless you want to keep the entire thing as a subfolder, you can just use this to make the overall project directory.

Project Layout

A Hugo project contains the following folders:

  • <project name> - the overall project folder
    • archetypes
    • assets
    • content - this is where the actual Markdown content of your site will go
    • data
    • hugo.toml - project configuration file
    • i18n
    • layouts
    • static
    • themes

Step 2 - layout files

Now, we need to add some minimal files to the site to help transform Markdown content into formatted HTML.

  1. Create layouts/home.html. This file will be the layout for the site’s homepage: 
    {{ define "main" }}
  {{ .Content }}
  <p>Hello from layouts/home!</p>
{{ end }}
  2. Create layouts/baseof.html. This file will be the layout for non-single pages (page trees, etc.) 
    <!DOCTYPE html>
<html lang="en" charset="utf-8">
<head>
</head>
<body>
    {{ block "main" . }}
    {{ end }}
</body>
</html>
  3. Create layouts/single.html. This file will be the layout for single pages (“leaves” in the page tree). 
    {{ define "main" }}
  {{ .Content }}
  <p>Hello from layouts/single!</p>
{{ end }}

Breaking themes

When you do eventually get to themes, you may need to delete these files if the theme expects to bring its own layouts.

Step 3 - content creation

Now, you can start creating the actual site content in content/. At this point, you just write a regular swath of Markdown files, linking to each other as needed. However, you typically want to include some “frontmatter”, which is YAML sandwiched between --- lines at the top of the file:

---
title: "Home page"
---
 
Hello, world!  This is the root of my site.

Put this in content/_index.md. Note the leading underscore - that’s significant.

  • _index.md: This creates a “branch bundle.” Essentially, this is transformed to a folder on the final pile of HTML files.
  • index.md: This creates a “leaf bundle.” Content in a folder with a non-underscored index.md is all glued together into one HTML page.

Step 4 - config and build

Now, edit hugo.toml as needed. Unless you know why you need them, add the following line:

disableKinds = ["taxonomy", "term"]

For most new users, this simply shuts up a misleading warning from the build process.

To build / run the server:

  • hugo build will build static HTML content. This content will end up in <project name>/public/.
  • hugo serve will not build content (it holds the page tree in memory), and launches a live server. The site will reload automatically when you change content files.

Graph View