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.
Related Resources
- English for Docusaurus Developers
- English for Eleventy (11ty) Developers
- English for Gatsby Developers
Bridging the Gap: Nuance for Non-Native Speakers
The core vocabulary of a technical writer – particularly one working with Hugo – focuses on clarity, precision, and actionable instructions. However, for developers whose first language isn’t English, navigating these nuances can be incredibly challenging. It’s not just about knowing what to say; it’s about conveying that meaning effectively in a way that resonates with a predominantly English-speaking team. This often involves understanding subtle differences in phrasing, acknowledging potential ambiguity, and demonstrating a proactive approach to communication. A seemingly simple request like “fix this” can carry significant weight – it implies a problem needs resolving, and the recipient might be wondering why it’s an issue. Similarly, overly verbose explanations can feel patronizing, while terse responses can come across as dismissive. The key is to build a bridge of understanding through careful word choice and a demonstrated willingness to collaborate.
One critical area often overlooked is the use of conditional language. Developers frequently use phrases like “should,” “could,” or “might” when suggesting improvements or outlining potential solutions. While perfectly acceptable in English, these words can be interpreted differently by non-native speakers who might perceive them as hedging their bets excessively, implying uncertainty where confidence is expected. Conversely, stating something definitively – “This must be fixed” - can feel demanding and potentially confrontational without a clear explanation of the reasoning behind the urgency. Learning to balance directness with diplomacy is essential. Furthermore, understanding the difference between “bug” and “issue” is important; ‘bug’ tends to carry a slightly more negative connotation than ‘issue,’ which can be framed as something needing attention rather than an inherent flaw.
A common scenario arises during code reviews. Imagine receiving this comment on a pull request: “This needs some work.” While seemingly innocuous, it’s incredibly vague. A better approach would be, “I noticed the calculate_tax function isn’t handling edge cases for VAT rates above 20%. Could you add a check for that?” This provides context, identifies the specific problem, and offers a clear direction for the developer to follow. Equally important is acknowledging your own understanding – “I’m not entirely sure about this integration but…” – demonstrating openness to feedback and collaboration. It’s about presenting yourself as part of a team, ready to learn and contribute effectively.
# Example: Using Hugo's `dump` command for generating documentation
hugo static -d docs --start-collections "my_project" --no-colorThis command demonstrates using the dump command within the Hugo ecosystem – a scenario where precise phrasing about data collection and output is vital. A non-native speaker would benefit from understanding that “no-color” prevents terminal clutter, while “start-collections” indicates which parts of the project’s documentation are included in the generated static files.