This is the second post of a series, you might want to check the first article (Intro) before reading this.
Hugo is very flexible in terms of configuration and organizing the content, you have a lot of options and you can do things in various ways. This might sound great but if you ask me, I rather like opinionated things where I don’t need to put a bunch of effort in figuring out best practices but the framework gives those to me (Convention over Configuration™). Unfortunately, this is not the case for Hugo.
Hugo has a convention for its high-level directory structure, I highly recommend reading the documentation about it and get familiar with most of them:
Archetypes are “content templates”. When you create a new content file using
hugo new, Hugo tries to find an archetype for your content in the
archetypes folder, e.g.:
hugo new posts/first.md-> “posts” archetype (
hugo new articles/first.md-> “articles” archetype (
archetypes/default.mdis the fallback
This is very handy if you want to create multiple types of content but even if you have just the default archetype, it saves time and produces consistent content across documents.
The posts archetype generates invalid content because of the categories (I always keep one and delete the rest).
The config files can be TOML, YAML or JSON placed as
config.json in the root folder but you can also use the config folder which gives you better structure and control. This means that different config objects can be placed in different files (e.g.:
params.toml), also you can have environment-specific configuration (e.g.:
Default environments are development with
hugo serveand production with
The Ananke theme, which is used by the Quick Start guide, needs
env = "production"to generate the
robots.txtfile correctly. To do this correctly, you need to use the
configfolder and hade different config for
This is where things can go wild. Since Hugo assumes that the structure that is used to organize the source files is used to organize the rendered site, you can almost do anything you want and I don’t know any official best practice here but the documentation gives you some pointers and revels the possibilities:
This is very important: read these pages of the documentation and try to understand the concepts as well as your possibilities, this is the key to organize your content.
What I’m doing (and why):
- I have a page bundle for the “normal” posts and another one for (hopefully) weekly news (“clamshell”)
- I put every “normal” post into its folder which is prefixed by the number of the post
- I put every “clamshell” post into its folder which contains only the date
- I put every page (e.g.: About) into its section
- This way I can do a few things:
- “normal” and “clamshell” posts are organized differently, they are ordered and separated
- Since every post is in its folder, I can put other resources next to the post (e.g.: images)
- I have different archetypes with different defaults for them
- I have different permalinks and organizer pages
- Pages are separated and I can put resources into the page folders