Creating Custom Partials
Relevant source files
The following files were used as context for generating this wiki page:Partials are a core feature of the Hugo static site generator used in this project. They are reusable pieces of template code stored in the layouts/partials/ directory. Their primary purpose is to keep the codebase DRY (Don't Repeat Yourself) by encapsulating components like headers, footers, navigation, and other repeated UI or logic elements. This allows for easier maintenance and consistency across the documentation site.
Partials can range from simple, static HTML snippets to complex, logic-driven templates that generate structured data like JSON. They are invoked from within other templates (layouts, shortcodes, or even other partials) and are a fundamental building block for creating and extending the site's structure and content.
Core Concepts
Directory Structure and Invocation
All partial templates reside within the layouts/partials/ directory. They can be organized into subdirectories for better management. A partial is called from another template using the partial function.
The basic syntax for including a partial is:
{{ partial "path/to/partial.html" . }}
The first argument is the path to the partial relative to the layouts/partials/ directory. The second argument, . (the dot), is the context passed to the partial, which gives it access to page- and site-level variables.
This diagram illustrates how a main page template includes various partials to construct the final HTML page.
Context Passing
The context passed to a partial determines what data it can access. While passing the entire page context (.) is common, a more specific context can be created and passed using Hugo's dict function. This is useful for partials that require specific, structured data.
For example, the img.html partial is called with a custom dictionary containing the root context, image source, and other attributes.
Source: layouts/schema/single.html:29-31
{{- partial "img.html" (dict "root" $dot "src" "icons/list-group-whats-next-arrow-1.png" "class" "img-fluid static" "alt" "more") -}}
This sequence diagram shows a layout template invoking partials with different contexts.
Sources: layouts/schema/single.html:12,29-32
Common Use Cases and Examples
Partials are used for a variety of purposes throughout the repository, from rendering simple UI components to complex data processing.
Standard UI Components
The most straightforward use of partials is to render common UI elements that appear on most or all pages.
| Partial File | Purpose | Example Location |
|---|---|---|
partials/footer/footer.html | Renders the global site footer. | Included in base layouts. |
partials/nav/left-nav.html | Renders the main left-hand navigation menu. | Included in base layouts. |
partials/breadcrumbs.html | Renders the breadcrumb navigation at the top of a page. | layouts/schema/single.html |
partials/whats-next/whats-next.html | Renders the "Further Reading" section at the bottom of content pages. | content/en/developers/integrations/create-an-integration-dashboard.md |
Sources: layouts/partials/footer/footer.html, layouts/partials/nav/left-nav.html, layouts/schema/single.html:12, content/en/developers/integrations/create-an-integration-dashboard.md (implicit use via partial call in layout)
Reusable Content Snippets
Partials are used to insert standardized content blocks into pages. A prime example is the whats-next.html partial, which is used to generate a "Further Reading" section. This partial is often called at the end of a content file's layout.
The use of this partial is evident in numerous markdown files that end with {{< partial name="whats-next/whats-next.html" >}}.
Sources: content/en/developers/integrations/create-an-integration-dashboard.md, content/en/all_guides.md
Image Handling
The project uses a dedicated partial for rendering images, as mentioned in the contribution guidelines. This standardizes how images are displayed and allows for global changes, such as adding lazy loading or other attributes. The img.html partial is called from various templates.
Sources: CONTRIBUTING.md:133, layouts/schema/single.html:29-32
Programmatic Content Generation
A more advanced use of partials is for generating non-HTML content, such as JSON files for search indexing. The layouts/_default/list.search.json template is a powerful example of this. It iterates through site pages and uses a series of partials from the partials/algolia/ directory to build a large JSON array that powers the site's search functionality.
This process demonstrates how partials can encapsulate complex data transformation logic.
The flow for generating the search index is as follows:
This diagram shows how list.search.json orchestrates several partials to aggregate data from different sources into a single JSON file.
Source: layouts/_default/list.search.json:34,70,73,76
A snippet from list.search.json shows the invocation of these partials:
{{- /* record for each individual section (split by h2 header) */ -}}
{{- partial "algolia/page-sections.json" (dict "context" $hugo_context "page" $page "title" $title "category" $category "subcategory" $subcategory "rank" $rank) -}}
...
{{- /* api pages are controlled by layout and not markdown, so we need to index them separately */ -}}
{{ partial "algolia/api-pages-full-index.json" (dict "context" $hugo_context) }}
{{- /* standard attributes pages */ -}}
{{ partial "algolia/standard-attributes.json" (dict "context" $hugo_context) }}
{{- /* glossary pages */ -}}
{{ partial "algolia/glossary.json" (dict "context" $hugo_context) }}
Sources: layouts/_default/list.search.json:34,70,73,76
Conclusion
Custom partials are a versatile and essential tool in the documentation-datadog repository. They enable developers to maintain a clean and modular codebase by abstracting reusable components. From simple UI elements like footers to complex data processing logic for search indexing, partials provide a scalable and efficient way to manage and extend the documentation site's functionality and appearance. Adhering to the practice of using partials for repeated elements is key to contributing effectively to this project.