Architecture / Code Overview?

the contribution guides are very detailed about general things like cloning and building the code, but I can’t find anything that explains the overall architecture of Hugo.

Is there anything that explains the overall design (what components interact how) and code flow (what is called when and what happens in parallel)?

Trying to understand the entire code base would probably take weeks without assistance, so I would really appreciate any pointers.

I try to estimate how much effort it would be to adjust Hugo to my needs. From studying the docs alone there seem to be quite a few blockers, thus I’m hesitant because the last migration of my project from Gitbook to Jekyll was much like one step forward, two steps back. But I might simply lack a “Hugo mindset” to see that all the tools are already there, ready to use. :slightly_smiling_face:


There is nothing that explains the overall design, code flow and mindset. It’s a Golang app. It’s not a finished product according to Semver rules (0.60 was just released, there is a big 0 in the front). I heard of Golang people who look at the code and understand it :wink: If you don’t speak Golang then don’t try to adjust Hugo to your needs. If you want to create a static website, then use it. It’s perfect for it. And speedy.

1 Like

Finished or not, there must have been design decisions in the making of Hugo. And it’s hard to reason about them as you can’t read the unwritten code. Also, there is great software which hasn’t or will never reach 1.0. It doesn’t say much about the quality or stability.

Here’s the situation: we already have a static site generator (the second in fact), customized to some extent, acceptable performance. What we don’t have is someone with extensive Ruby knowledge for Jekyll, so fixing bugs and implementing additional features is quite a struggle. We do have a dedicated Go team on the other hand. But I am the one who has to assess possible alternatives and convince management to invest time and money for yet another migration. And so far there are no real reasons to switch, because Hugo lacks too many things:

  • Compliant Markdown parser (blackfriday has some critical bugs)
  • Plugin system? (custom Go code, not templating)
  • Access to AST for advanced validation and ability to modify nodes on the fly
  • Extensibility for non-text output formats

There are also dozens of small things that are a must, but I’m sure most of them are supported by Hugo. I have to check in detail though.

1 Like

0.60.0 was just released. Goldmark is now the default markdown parser.

What specifically do you need a plugin system for? Maybe it can be solved another way.

Do you have a specific example in mind?

Great to hear about the parser switch. We use deeply nested lists a lot, so blackfriday’s list-related bugs were a real blocker.

We have semi-structured data files from which a lot of content is generated. It requires some preprocessing including a custom parser with a state machine of sorts and recursive calls to get the data into the correct shape for rendering. In Jekyll this is done through a plug-in script with a few hundred lines of code at build time.

Other extensions implement versioning and a version switcher (the data part, the actual switcher uses JavaScript), a two-tiered navigation, previous/next links etc. There is also a third-party plug-in to extract text content for indexing.

I would like to access the AST to find broken markup, e.g. **emphasis* with an asterisk missing at the end. Grepping for such mistakes is difficult (many false-positives or inefficient regex). It would be much easier to detect in context (e.g. ignore inline and fenced code).

Output formats would be PDF and ePUB. Pages media requires some automatic content changes / different rendering to work properly, e.g. convert external links to text + footnotes with the URL.

See this GitHub issue:

If you mean versioning as in “let me read the latest version of your docs, or some previous version”. Then the things you mentioned can all be done with Hugo + JavaScript.

Others will have to chime in on AST and PDF/ePUB.

I second that. An overview of the architectural structure of the Hugo project would be very helpful in bringing new contributors on board. I for myself struggle to fully grasp the code structure and where would be the right place to put an addition or where to find the possible source of a bug etc.

A good example I know of would be the structure documentation of the Blender3D project.

See also this article on

This could be improved, but there is a list of package descriptions based up on the package godocs at

1 Like