Some brief notes to self on how Hugo is working

Oct 07, 2019

These are some notes on how hugo is working for this website in particular. I haven’t found anywhere that enumerates these things succinctly, so I’m attempting to do that here.

Hugo reads the theme from the config.toml file. From there, it looks in the themes directory for a folder with the theme name (this folder could, but doesn’t have to, contain a theme.toml file).
The index view renders the layout found for the theme in $THEME_NAME/layouts/_default/baseof.html. In my theme, this layout loads partials with the <head> of the document, and a sidebar and footer, then delegates to the defined main block. main could be defined in any layout file, and I define it in the index.html file in my site layout (which is located at $SITE_ROOT/layouts/index.html).

Hugo will search for layouts using a priority based lookup that depends on several parameters. For example, the home layout search path is as follows (note that the project specific layouts are preferred to theme layouts):

layouts/index.html.html
themes/<THEME>/layouts/index.html.html
layouts/home.html.html
themes/<THEME>/layouts/home.html.html
layouts/list.html.html
themes/<THEME>/layouts/list.html.html
layouts/index.html
themes/<THEME>/layouts/index.html
layouts/home.html
themes/<THEME>/layouts/home.html
layouts/list.html
themes/<THEME>/layouts/list.html
layouts/_default/index.html.html
themes/<THEME>/layouts/_default/index.html.html
layouts/_default/home.html.html
themes/<THEME>/layouts/_default/home.html.html
layouts/_default/list.html.html
themes/<THEME>/layouts/_default/list.html.html
layouts/_default/index.html
themes/<THEME>/layouts/_default/index.html
layouts/_default/home.html
themes/<THEME>/layouts/_default/home.html
layouts/_default/list.html
themes/<THEME>/layouts/_default/list.html

Other than the home page, layouts are not searched for in the root of the layouts directory.
Partials are found in one of two places:

layouts/partials/*<PARTIALNAME>.html
themes/<THEME>/layouts/partials/*<PARTIALNAME>.html

You can use subdirectories, and refer to them in the partial call, e.g. {{ partial "subdir/footer.html" }}
Content types are set by either the subdirectory under content or by explicitly setting it in the front matter of the content. e.g. this post is at content/posts/hugo_workings.md which makes it a posts content-type. I could change that by setting type: othertype in the yaml front matter.
content/_index.md is the content for the home page
_index.md vs index.md: _index.md means that the content and containing folder refer to a list and a “branch” page bundle (i.e. contains more sub pages); index.md means that the content and containing folder are a single page bundle (a “leaf” bundle).
The .Permalink property on a post generates a link which loads the single.html layout with the contents of a single post.

Setting up css and js processing is best done with an external pipeline like webpack. Webpack can then be configured to start the hugo server for us, so that our single entry point for dev and building is via Yarn. Something like this to set your environment in webpack.config.js:

  function set() {
    switch (process.env.APP_ENV) {
    case 'dev':
      return {
        watch: true,
        filename: '[name]',
        command: 'hugo serve --buildDrafts=true'
      }
    default:
      return {
        watch: false,
        filename: '[name].[hash]',
        command: 'hugo'
      }
    }
  }

then in `package.json`, add the scripts blocks to call webpack:
```js
    "scripts": {
      "build": "webpack -p",
      "start": "APP_ENV=dev webpack"
    },

this way, I can use yarn start for development and yarn build to package the site.