Mireille's blog
Fun things, ideas about technology, cheat sheets, data + code.

Hugo

A cheat sheet for Hugo. Things that may not be straight forward or not mentioned in the documentation.

Sub-modules

When adding a theme, if you used the sub-module command:

1
2
3
4
5
git submodule add https://github.com/xxx/gohugo-theme-xxx.git themes/xxx;\

# Edit your config.toml configuration file
# and add the xxx theme.
echo 'theme = "xxx"' >> config.toml

Don't forget to init and update the sub-module in git. You will then see the files locally and can tinker with them.

1
2
git submodule init
git submodule update --remote

A directory for images and other static content.

In config.toml, add where you static directory should be. Static means css, images and other static files like multimedia or text/pdf etc…

In config.toml, add:

staticDir = ["static"]

For many directories

staticDir = ["static" , "pdf", "something"]

After you add the static setting in the config file, make sure to create the directory and sub-directories if any. For example I have static/images and static/css.

To reference an image in your post, you don't need to type in the name of the static folder, just use the relative path, for example: images/something.png

Overwriting theme template

Create a new folder called layouts. There is no need to mention this anywhere in the config.toml file.

Anything you create here, will overwrite what is in your theme.

For example, I created a sub-folder called page and put index.html in it to overwrite the index page. To overwrite the top section, I created a folder called partials and put top.html in it. Here you will have to follow your theme structure to overwrite it.

Overwriting css

In config.toml, list your custom stylesheets using a parameters settings:

[params]
    stylesheets = ["custom.css" , "print.css"]

Here, the only way to add stylesheet to the theme was by overwriting the top or header. I included a loop that reads the above setting in config.toml and just adds them.

{{ range .Site.Params.stylesheets }}
    <link href="/css/{{ . }}" rel="stylesheet" type="text/css" />
{{ end }}

I assume a good practice for theme makers is to always include and document a way to add custom css.

Hugo could have a better way to do this… this was the best way I found after looking around.

Adding a new post from command line

hugo new post/xxx-title-of-your-post.md

This will generate a new post with today's time stamp. make sure to enter the full path. This command is slightly different from what I've seen in other static generators.

Enabling reStructured text with Hugo and Netlify.

A good background read is this article on Netlify that explains how they build sites and run scripts.

To enable reStructured text, you'll need to install something like rst2html5.py

pip install rst2html5 && pip freeze > requirements.txt

This will install the package for you an generate the requirments.txt file. You can of course configure other packages (see above link for what you can and can't do).

Once you push your code to GitHub/GitLab/Bitbucket the build will run on Netlify and you should be good to go.