Thoughts about Hugo's documentation

Meta
1

Hi Hugo maintainers,

I’m a theme contributor who sometimes fixes bugs. I’m excited to hear that the documentation is being restructured using the Diátaxis framework.

First, thanks for your ongoing maintenance and responses to the community. Providing example repositories when people ask questions takes a lot of effort and is really helpful.

I’d like to share some thoughts about the documentation. If anything comes across as critical, that’s not my intention, I just want to help Hugo’s community and users.

I’m not sure if this is the right place to share this, and many of these issues have probably been considered already or may be difficult to implement. But as a user, I thought I might offer a different perspective from the developers.

I’ve looked through these documentation sites extensively, and much of my feedback comes from them:

Current Issues I’ve Noticed

As a reader, the main problems I encounter are:

  1. Hard to locate specific content, I use search 90% of the time instead of navigating through menus, while with other docs I rarely need search

  2. Unclear reading progression, it’s hard to know where I am or what to read next

Documentation Ordering

This feels like the most important issue to address. The current alphabetical sorting makes the docs harder to navigate, and the behavior is inconsistent. Most sections use alphabetical order, but important content like the new template system gets moved to the front.

This should be fixed with the Diátaxis restructure though.

Card Layout

The card layout creates navigation issues for me. I often lose track of where I am in the documentation and what to read next. Cards have both horizontal and vertical relationships, while other documentation sites only have vertical relationships between sections, creating a clear reading flow.

When I try to find information visually instead of using search, I have to read through all the title names everytime to find what I need (even for documents I just read), or mentally go through the alphabet for alphabetically sorted sections (this doesn’t apply to functions and methods, which are naturally suited for alphabetical ordering).

Three-Column Layout

The three documentation examples I mentioned all use a three-column layout: left sidebar for document structure, main content in the center, and right sidebar with page TOC.

I used to wonder why so many docs use this layout. It seemed boring that every site looks the same. But after thinking about it, I realized everyone uses it because it is the most effective for reading. The main benefit is:

You always know where you are in the documentation and what comes before/after.

This lets authors clearly guide users on “how to read the documentation.” The current card layout with inconsistent sorting makes it hard to understand progress and what to read next. I think many people end up jumping around the docs, which means they’ll inevitably miss things.

The three-column layout also addresses another UX issue: Hugo’s current documentation lacks clear visual separation between “In this section” and “On this page” navigation. Users must scroll down to access the page TOC, but since they typically arrive at a page from the section level, they’re immediately presented with the same section information they just navigated from. This also forces users to scroll back up after reading to navigate to the next section.

Top Navigation Bar

The top nav bar would be a perfect match for implementing Diátaxis. Looking at VitePress/Docusaurus docs, the synergy is clear:

  1. Basic usage goes in docs/guides (whatever the name)

  2. Advanced usage goes in API. Regular users never need to click into API unless they’re customizing themes

This reduces complexity by about 70% for regular users. Most people probably never need to read functions/methods section, and this design lets users know “I never need to click into the API section because I’m not customizing or writing themes.”

Diátaxis Ordering

uv has the clearest documentation structure I’ve seen, which is why I’m referencing it:

  1. Getting Started lets you get something working quickly

  2. Guides cover daily usage with shorter articles

  3. Concepts are more detailed with longer articles. Also, I notice that when I see the “Package indexes” section I naturally don’t want to read it, and everything after that is indeed non-essential

  4. Reference section listing all usage (corresponding to the top nav position for API mentioned earlier)

  5. All sections flow logically from top to the bottom, creating a clear learning path that our docs currently lack

Though uv is a different type of tool from Hugo, I think we can still learn from their approach, especially regarding Diátaxis implementation.

Usage Guidance

Following Diátaxis principles, I think more effort should go into describing theme usage, since most people are users rather than developers. For example, as someone who sometimes answers questions for theme users, there are many people directly modifying theme folder contents instead of overriding them (when I think this is actually one of Hugo’s major features that other SSGs can’t match), and some users even get confused between _index.md and index.md. These basic topics are surprisingly hard to locate in the current documentation structure.

Misc

Section naming: from my perspective, these two names seem similar:

  1. functions

  2. methods

I don’t really think about the difference between them. In my mind they’re both “things I use in layouts”—but they’re separate sections. Maybe the distinction is necessary, but they should at least be listed together.

Javascript: the current documentation pages have transition effects that cause issues. When I’m quickly jumping between pages, I often need to click the same link multiple times before it actually navigates.

Summary

I believe that separating documentation for general users and developers, and intentionally guiding users through a logical reading sequence, would significantly improve the overall experience. I’m really looking forward to the transition to the Diátaxis framework and am confident these changes will make Hugo’s documentation even more effective. Thanks again for all your ongoing maintenance work!

3 Likes
2

A shorter summary of my post:

  1. Separating beginner and developer documentation would be a quick and easy win. This alone would greatly reduce cognitive load for most users.

  2. The current documentation is detailed enough and doesn’t need more extensive explanations, except for some beginner-oriented content.

  3. Content ordering is the key issue, which is exactly what the Diátaxis framework addresses.

  4. Layout should guide readers without explicit instruction. Simply reordering articles is not enough, the layout needs to be more linear to support clear reading progression.

1 Like
3

More examples would probably be welcome as well.

1 Like
4

View the response here Are the documentation sections in the wrong order?.

5

Thanks for the context! I reviewed the old documentation version, which indeed used a 3-column layout. The main issue was that the left and right columns didn’t scroll properly, which undermined the advantages of the 3-column layout. Otherwise, it offered good navigation and a Diátaxis-style logical order.

Since the old design already followed a 3-column layout with Diátaxis progression, my article adds limited new insight. So I deside to note my perspective, focusing on the Getting Started section for beginners with no prior website or SSG knowledge.

TL;DR:

  1. Getting Started feels brief and could include more practical, high-impact usage.
  2. Content irrelevant to basic usage might be excluded. Showing commands once per section could reduce confusion.
  3. Configuration basics like permalinks, Front Matter, Languages, menus, and segments could be included.
  4. A What’s Next section could guide users to the next step explicitly, complementing the 3-column layout. For example, users might want themes after Quick Start or understanding the Directory structure.
  5. Letting users skip full pages, not just middle sections, would improve usability, e.g., the deployment page.

Quick-start:

  1. I’m not entirely sure how to modify this documentation, but one thing that puzzled me before was why setting baseURL changed the hugo server output from ‘Web Server is available at //localhost:1313/’ to ‘http://localhost:1313/’. The documentation mentions this setting is for “your production site,” but it seemed to affect development output too.

  2. “Publish the site” (build the site) appears quite early. For users who might not even know markdown, let alone HTTP servers, using the hugo build command might not be immediately meaningful.

  3. I wonder if “Ask for help” and “Other resources” might work better at the end of the entire Getting Started section rather than in Quick-start? It feels like directing readers away from the documentation just as they’re getting started.

Basic usage:

  1. This page seems to provide relatively little actionable information for beginners. As the TL;DR suggests, newcomers could skip this page without much impact since the content isn’t needed for daily use or has been covered elsewhere.

  2. Beginners might not find the public directory contents particularly relevant since they’re still figuring out the project structure itself. For newcomers, build directory contents might not feel very “basic.”

Directory structure:

This was definitely my biggest hurdle as a newcomer. The documentation is quite detailed, but I think it might be a bit overwhelming:

  1. The directory tree codeblock under “Creates this directory structure” could perhaps include brief descriptions of directory purposes. I found myself wanting a quick visual reference rather than reading through detailed text lists, and text combined with visuals tends to be much easier to understand and remember instantly.

  2. The codeblock above, plus config/_default variants and the public directory, wastes 1.5 viewports, which might encourage fast scrolling.

  3. Concepts like Union file system feel quite advanced for this stage. Beginners now might be more interested in how to do basic configurations/modify themes through overrides rather than modifying the themes directory directly, but this approach isn’t really covered here.

  4. Beginners probably don’t need to worry about “hugo new theme” yet. This explanation might not be immediately relevant, since newcomers are usually focused on understanding markdown/Hugo project structure/git usage/frontmatter/configuration first. Internal architecture typically becomes relevant much later in the learning path.

  5. Theme skeleton has the same problem as Union file system.

  6. Beginners typically work with single themes, so multi-theme scenarios might not belong in “getting started.”

  7. It might be clearer to explicitly state something like “files in the project root will override theme files.”

  8. The structure of content directory seems really fundamental for Hugo but doesn’t get much coverage here. Should users use content/posts/article/index.md or content/posts/article.md?

  9. Should mention all relevant files, like explaining whether the resources directory and hugo_stats.json should be git-tracked, since this seems to be a common source of confusion, even among theme developers who sometimes don’t include resources in .gitignore.

Quick reference:

In the old documentation, this was part of getting started, so I’m including it here. The problem of quick reference is it’s not quick. The content of this section actually plays the same roll as reference in uv, which should be placed at the end of the document.

At least I wanted to log my beginner experience to hopefully avoid similar issues even after implementing Diátaxis.