English for Hugo Static Site Developers
Vocabulary for developers building sites with Hugo, the Go-based static site generator — content sections, taxonomies, shortcodes, and the fast build pipeline — for English-speaking documentation teams.
Hugo is a static site generator written in Go, known above all for build speed — thousands of pages compiling in well under a second. Its vocabulary reflects its content-first design: “content sections,” “taxonomies,” “archetypes.” If you’re documenting or maintaining a Hugo-based site — often a documentation portal or a large content site — this guide gives you the English to discuss it clearly.
Content Organisation
Content section — a top-level folder under content/ that Hugo treats as a distinct content type, each potentially with its own templates and list pages.
“Blog posts live in the posts section, and documentation lives in the docs section — each has its own list template and URL structure.”
Front matter — the metadata block (YAML, TOML, or JSON) at the top of a content file, defining title, date, tags, and any custom fields.
“We use TOML front matter across the whole site for consistency — mixing formats file to file just makes it harder to grep for a specific field.”
Archetype — a template file used to pre-fill front matter when creating new content of a given type, via hugo new.
“Running
hugo new posts/my-article.mdpulls from thepostsarchetype, so every new post starts with the right front matter fields already in place.”
Page bundle — a folder-based way of grouping a content file with its own local resources (images, other files) so they travel together instead of being scattered across a shared assets folder.
“We switched the case studies to page bundles — each one’s images now live right next to its markdown file instead of in a separate top-level assets folder.”
Taxonomies
Taxonomy
A taxonomy is a way of classifying content — tags and categories are the built-in examples, but you can define custom taxonomies (like “series” or “difficulty level”).
“We added a custom
difficultytaxonomy so readers can browse tutorials by ‘beginner,’ ‘intermediate,’ or ‘advanced’ directly from the site.”
Term
A term is a specific value within a taxonomy — for example, “kubernetes” is a term within the “tags” taxonomy.
“Hugo automatically generates a list page for every term — visiting
/tags/kubernetes/shows every post tagged with that term, with no manual work required.”
Templates and Rendering
Layout lookup order — Hugo’s rule-based system for deciding which template file applies to a given piece of content, based on its section, type, and output format.
“When a page rendered with the wrong layout, the fix was understanding Hugo’s lookup order — a more specific template in the section folder should have taken priority.”
Partial — a reusable template snippet (like a header or a card component) included from other templates, avoiding duplication.
“We extracted the article card markup into a partial so it’s identical whether it’s rendered on the homepage, the tag page, or the search results.”
Shortcode — a reusable snippet callable from within markdown content itself, for things regular markdown can’t express — embeds, callout boxes, or custom layout blocks.
“Authors use the
{{< callout >}}shortcode to add a warning box in the middle of a markdown article, without writing raw HTML.”
Render hook — a way to override how Hugo renders a specific markdown element (like links or images) site-wide, without touching individual content files.
“We added a render hook for images so every image in the site automatically gets lazy-loading attributes, without authors needing to write any HTML.”
Build Performance Vocabulary
Build time — how long Hugo takes to generate the full site; commonly cited in the low hundreds of milliseconds even for large sites, a major reason teams choose it.
“Our documentation site has over 3,000 pages and still builds in under a second — that’s the main reason we haven’t felt pressure to move to anything else.”
Live reload — Hugo’s development server automatically rebuilds and refreshes the browser on file changes, giving near-instant feedback while writing content.
“Live reload means an author can preview a markdown edit in the browser almost the instant they save the file.”
Multilingual and Output Formats
i18n / multilingual mode — Hugo’s built-in support for maintaining the same site in multiple languages, with translated content organised by locale.
“We run true multilingual mode, not just translated strings — each language has its own content tree, and Hugo generates a fully separate URL structure per locale.”
Output format — Hugo can render the same content as HTML, JSON, RSS, or other formats from one content source, configured per section.
“We added a JSON output format for our docs so a separate search tool can index the content without scraping the rendered HTML.”
Explaining Hugo to a Team
| Situation | Phrase |
|---|---|
| Justifying the choice for a large docs site | ”With thousands of pages, build speed matters — Hugo rebuilds this entire site in under a second, so contributors get instant feedback.” |
| Explaining a taxonomy to a content author | ”Assign the ‘difficulty’ term in the front matter, and Hugo automatically adds this article to the right browse-by-difficulty page.” |
| Describing a render hook change | ”We didn’t touch any content files — the render hook change means every image site-wide now lazy-loads automatically.” |
| Discussing multilingual setup | ”Each language has its own content tree, so a missing translation shows up as a genuinely missing file, not a partially translated page.” |
Common Mistakes
- Calling a partial a “component” without clarifying it has no client-side behaviour — it’s a server-side template include, not an interactive unit.
- Saying “we added a category” when the more precise term might be taxonomy or term, depending on whether you mean the classification system or a specific value within it.
- Describing Hugo’s speed as “because it’s static” — many static site generators are far slower; Hugo’s speed specifically comes from being written in Go with heavy internal caching.
Practice Exercise
- Explain, in two sentences, the difference between a taxonomy and a term.
- Write a short onboarding note for a content author explaining how to use an archetype to create a new post with the right front matter.
- Draft a one-paragraph justification for choosing Hugo over a JavaScript-based static site generator for a 3,000-page documentation site.