Hugo Layouts and Partials
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Documentation website is built using the Hugo static site generator. Its structure and appearance are defined by a system of layouts and partials. This system separates content (Markdown files) from presentation (HTML templates), allowing for consistent design and reusable components across the site. Base layouts provide the foundational HTML structure, while specific layouts like single.html render individual content pages. Reusable partials are used for common UI elements such as headers, sidebars, and metadata generation, promoting modularity and maintainability.
This architecture also supports specialized layouts for different content types, such as the automatically generated CLI reference pages, which pull data from YAML files.
Core Layout Architecture
The rendering of any page begins with a base layout, which is then populated by a more specific layout and the page's content.
Template Inheritance Flow
This diagram shows how the final HTML page is assembled from the base template, a specific page layout, and the Markdown content.
Base Layout (baseof.html)
The baseof.html file is the root template for all pages on the site. It defines the main HTML document structure, including the <html>, <head>, and <body> tags. It uses Hugo's block/define syntax to create sections that can be overridden by more specific layouts.
Key responsibilities of baseof.html:
- Defines the main
<html>tag and language attributes. - Contains the
<head>section, which includes partials for metadata and schemas. - Includes the site header and footer.
- Defines a
mainblock that child templates likesingle.htmlwill populate with content.
Sources: layouts/_default/baseof.html
Page Layouts
Page layouts define the structure for specific types of content. The docker-docs repository uses several, including a default for standard pages and specialized ones for CLI documentation.
Default Page Layout (single.html)
This is the default layout for a single piece of content (e.g., a documentation page written in Markdown). It defines the main content area, including breadcrumbs, the page title, the content itself, and a sidebar for the table of contents.
The following diagram illustrates the rendering sequence for a standard documentation page.
Specialized CLI Layout (scout-cli.html)
To handle generated CLI documentation, a specialized layout scout-cli.html is used. Instead of rendering Markdown content directly, this layout fetches data from YAML files located in the site.Data directory. It uses parameters from the page's front matter to locate the correct data file.
| Parameter | Description |
|---|---|
datafolder | The sub-directory within data/ containing the YAML file. |
datafile | The name of the YAML file (without extension) to load. |
markdownfile | An optional path to a markdown file for extended descriptions and examples. |
This layout dynamically builds the page by iterating through the YAML data for descriptions, usage, aliases, and options, and renders them into HTML tables.
Sources: layouts/_default/scout-cli.html:2-10, layouts/_default/scout-cli.html:100-119
Reusable Components (Partials)
Partials are small, reusable templates included within layouts to build up a full page. This modular approach keeps the layouts clean and easy to manage.
Metadata and SEO
A critical function of the partials is to generate metadata for search engine optimization (SEO) and social media sharing.
Head Metadata (meta.html)
The meta.html partial is included in the <head> of every page. It is responsible for generating:
- The page
<title>. - The
robotsmeta tag to control indexing (noindexfor non-production builds or wheresitemap: falseis set). descriptionandkeywordsmeta tags.- The canonical URL link.
- Twitter Card and Open Graph metadata for social sharing, using the page's title, description, and a default thumbnail image.
Sources: layouts/partials/meta.html
Schema.org Structured Data (schema.html)
The schema.html partial generates JSON-LD structured data, which helps search engines understand the content and context of the page. It creates two main schema types: TechArticle and BreadcrumbList.
The data for these schemas is aggregated from various sources:
- Page Parameters: Title, description, permalink.
- Git Info:
PublishDateandLastmodfor publication and modification dates. - Site Configuration: Site base URL and organization details.
- Front Matter: The
timeparameter (e.g., "30 minutes") is converted to ISO 8601 duration format (PT30M).
This diagram shows the data flow for creating the TechArticle schema.
Sources: layouts/partials/schema.html
Navigation Components
Navigation elements like the main header and sidebar are also managed through partials.
Header (header.html)
The header.html partial constructs the main site header. The navigation links displayed in the header are not hardcoded but are dynamically generated by ranging over the main menu defined in hugo.yaml.
# hugo.yaml
menus:
# Site header menu
main:
- name: Get started
pageRef: /get-started/
weight: 1
- name: Guides
pageRef: /guides/
weight: 2
# ... and so on
Sources: layouts/partials/header.html, hugo.yaml:104-115
Main Sidebar (mainnav.html)
The mainnav.html partial is responsible for rendering the primary left-hand sidebar navigation. It dynamically generates the navigation tree based on the content structure of the site. It also includes logic to display badges next to navigation items if specified in a page's front matter.
Sources: layouts/partials/sidebar/mainnav.html
Summary
The Hugo layout and partial system in the docker-docs repository provides a powerful and flexible framework for generating the documentation website. By separating content from presentation and using modular components, the system is both scalable and maintainable. Key features include a clear template inheritance model, specialized layouts for different content types like CLI references, and robust, automated generation of SEO-critical metadata and structured data. This architecture ensures a consistent user experience while allowing developers and writers to focus on creating high-quality content.