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.

Directory Structure

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
• config
• content
• data
• layouts
• static
• themes

Archetypes

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 (archetypes/posts.md)
• hugo new articles/first.md -> “articles” archetype (archetypes/articles.md)
• archetypes/default.md is 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.

I highly recommend to check out the documentation, also feel free to check out my archetypes.

WARNING:

The posts archetype generates invalid content because of the categories (I always keep one and delete the rest).

Config

The config files can be TOML, YAML or JSON placed as config.toml, config.yaml, or 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.: menus.toml, params.toml), also you can have environment-specific configuration (e.g.: development, production).

Default environments are development with hugo serve and production with hugo.

WARNING:

The Ananke theme, which is used by the Quick Start guide, needs env = "production" to generate the robots.txt file correctly. To do this correctly, you need to use the config folder and hade different config for development and production environments.

I highly recommend to check out the documentation, also feel free to check out my config.

Content

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:

• Content Organization
• Page Bundles
• Front Matter
• Taxonomies
• URL Management

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
  (e.g.: 001-hello-world)
• I put every “clamshell” post into its folder which contains only the date
  (e.g.: 2020-05-20)
• 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 /posts/ and /clamshell/
  • Pages are separated and I can put resources into the page folders

Posts in this series

• Intro
• Content
• Deploy