Hugo Partials Reference

This page provides a reference for FixIt’s Hugo partials (layouts/_partials/), covering template functions, plugins, and layout components. Each partial entry includes its parameters, return values, and usage examples.

The FixIt theme provides 97 Hugo partials across 13 groups.

Groups

• _debug/ — 2 partials
• base/ — 7 partials
• base/head/ — 3 partials
• feed/ — 1 partial
• function/ — 36 partials
• gen/ — 2 partials
• home/ — 1 partial
• init/ — 8 partials
• plugin/ — 20 partials
• section/ — 1 partial
• single/ — 13 partials
• store/ — 2 partials
• (root) — 1 partial

_debug/

Debug utilities for development.

2 partials

_debug/dump.html

This is a debug partial that dumps the current context.

Example:

1

{{- partial "_debug/dump.html" . -}}

_debug/template-call-stack.html

Render template call stack for debugging purpose.

Example:

1

{{- partial "_debug/template-call-stack.html" . -}}

base/

Core layout partials (header, footer, breadcrumb, paginator, comment, widgets, assets).

7 partials

base/assets.html

Assets Partial - Asset orchestration for page scripts and styles.

This partial collects feature flags and page/site params, then registers required CSS/JS resources through store/style.html and store/script.html.

Key responsibilities:

• Resolve optional third-party libraries and plugin integrations
• Build per-page runtime config and emit window.config
• Build and register core bundles (file-tree, mermaid, main, custom)
• Append page-injected style/script arrays and analytics hooks

Called from: layouts/baseof.html.

base/breadcrumb.html

Render breadcrumb navigation for the current page.

Displays a hierarchical path from the site root to the current page. Supports configurable separator, sticky mode, home visibility, and title capitalization.

Called from: layouts/baseof.html.

base/comment.html

Comment system integration partial.

Renders the comment container and injects provider-specific CSS/JS assets. Supported providers: Artalk, Disqus, Gitalk, Valine, Waline, Facebook, Telegram, Commento, Utterances, Twikoo, Giscus, and custom comment systems.

Called from: layouts/baseof.html.

base/footer.html

Site footer partial.

Renders the page footer with configurable sections:

• Powered by (Hugo and FixIt theme links)
• Copyright (year, author, license)
• Site running time counter
• Visitor statistics (busuanzi)
• Gov/ICP filing information (beian)

Called from: layouts/baseof.html.

base/header.html

Desktop and mobile site header with navigation.

Renders two header variants:

• Desktop: full navigation menu with submenus, search trigger, theme switch, and language switcher.
• Mobile: compact header with hamburger menu, search, theme switch, and language select.

Both support TypeIt animation for title/subtitle, GitHub corner integration, and custom menu items.

Called from: layouts/baseof.html.

base/paginator.html

Pagination component with ellipsis.

Renders a paginated page list with ellipsis for large page counts. Shows page numbers near the current page and ellipsis markers for distant ranges.

base/widgets.html

Global widget layer partial.

Renders floating UI elements across all pages:

• GitHub corner link
• Navigation dialog
• Search dialog modal
• Reading progress bar
• Link guard confirmation dialog
• Service worker update notification
• Fixed action buttons (back-to-top, TOC drawer, view comments)
• Custom widgets
• Noscript warning

Called from: layouts/baseof.html.

base/head/

3 partials

base/head/css.html

CSS Partial - Base and page-specific CSS loading.

Loads the main stylesheet (every page) and conditionally loads page-specific CSS based on .Kind, .Layout, and .RelPermalink.

Called from: base/head/index.html.

base/head/index.html

Head Partial - Comprehensive head section template.

This partial consolidates all head-related content including:

• META: Meta tags for SEO, Open Graph, Twitter Cards, and app metadata
• LINK: Favicon, canonical links, RSS feeds, and CSS stylesheet loading
• SEO: Schema.org structured data for pages and homepage
• SCRIPT: Early-loaded scripts (e.g., theme color scheme detection)

Called from: base/baseof.html.

base/head/twitter-cards.html

Extends Hugo’s embedded twitter_cards partial: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_partials/twitter_cards.html.

Key differences:

• Generates twitter:site / twitter:creator from site params (.Site.Params.social.twitter)
• The param can be a string or a map; when it’s a map, reads creator/id

feed/

RSS feed generation.

1 partial

feed/rss.html

RSS feed generation partial.

Renders an RSS 2.0 XML feed for the current section or home page. Supports full-text or summary mode, filters out password-protected and hidden pages, and includes cover images, author info, and follow challenge tags.

function/

Reusable utility and helper function partials.

36 partials

function/camel-case-keys.html

Convert snake_case config keys to camelCase recursively.

This is mainly used to avoid problems caused by Hugo’s case-insensitive config key parsing. Keep config keys in snake_case, then convert them here for stable access in templates and JS.

Parameters:

Returns: Map|Slice - A new value with camelCase keys

Example:

1
2
3

// Simple Map conversion
Input: dict "code_block" true "max_shown_lines" 10 "line_nos" false
Output: dict "codeBlock" true "maxShownLines" 10 "lineNos" false

1
2
3

// Nested Map conversion
Input: dict "code_block" (dict "enable_wrapper" true)
Output: dict "codeBlock" (dict "enableWrapper" true)

1
2
3

// Array of Maps conversion
Input: slice (dict "user_name" "John") (dict "user_age" 30)
Output: slice (dict "userName" "John") (dict "userAge" 30)

1
2

// Practical usage in templates
{{- $siteParams := partial "function/camel-case-keys.html" .Site.Params -}}

function/camel-case.html

Convert a snake_case string to camelCase. Strategy: split by “_”, capitalize first letter of each part (except first), then concatenate.

Parameters:

Returns: String - The camelCase string

Example:

1
2

// "max_shown_lines" -> "maxShownLines"
{{- partial "function/camel-case.html" "max_shown_lines" -}}

function/code-copy-btn.html

Code copy button for no-classic mode code blocks.

function/code-expand-btn.html

Code expand button for code blocks.

function/code-header.html

Code header for classic mode code blocks.

function/color-preview.html

Color preview rendering This function adds color visualization to code elements that contain ONLY color values. Supports HEX, RGB, and HSL color formats like GitHub’s color preview feature.

Examples: #0969DA -> displays a blue color preview circle rgb(9, 105, 218) -> displays a blue color preview circle hsl(212, 92%, 45%) -> displays a blue color preview circle.

But excludes: `#0969DA` -> renders as normal code (syntax example) test #0969DA -> renders as normal code (has leading text) #0969DA -> renders as normal code (has leading space) #0969DA -> renders as normal code (has trailing space).

function/content.html

Content processing pipeline partial.

Applies a chain of content transformations: ruby annotations, fractions, Font Awesome icons, task lists, marked text, color preview, and HTML escaping.

Parameters:

Returns: String - The processed content

function/dos2unix.html

Unify new lines symbol.

function/escape.html

Escape character.

function/escapeurl.html

Escape URL special characters to query format, e.g: # -> %23.

See: https://github.com/hugo-fixit/FixIt/issues/245.

function/fontawesome.html

Font Awesome.

function/format-number.html

Format a number with a specific precision and add ‘k’ if it’s greater than 1000 Usage: {{ partial “function/format-number” (dict “PRECISION” 2 “NUMBER” 5201314) }} Example Output: 19980.52k.

function/fraction.html

Fraction.

function/get-author-map.html

Get author in map format.

Parameters:

Example:

1

{{- $author := partial "function/get-author-map.html" .Params.author -}}

function/get-cover.html

Get the cover image for a page.

Resolves the cover image by checking front matter params first, then page resources. Supports remote URLs, inline data URIs, and local page/global resources.

Resolution order: 1. Front matter: featured_image_preview (if Preview=true) or featured_image 2. Page resources: “featured-image-preview” (if Preview=true), then “featured-image” 3. Global resources: by the front matter value as a path.

Parameters:

Returns: Map - dict with:

Example:

1
2

{{- $cover := dict "Page" . | partial "function/get-cover.html" -}}
{{- with $cover.URL -}}<img src="{{ . }}">{{- end -}}

1
2

{{- $cover := dict "Page" . "Preview" true | partial "function/get-cover.html" -}}
{{- dict "Src" $cover.URL "Resources" .Resources "Matches" $cover.Matches | partial "plugin/image.html" -}}

function/get-file-tree.html

Build structured tree data from filesystem with root path validation.

It attempts to resolve the path relative to the root of your project directory. If a matching directory is not found, it will attempt to resolve the path relative to the contentDir. A leading path separator (/) is optional.

NOTE: For performance reasons, the recursion depth is limited to 10 levels by default.

Parameters:

Returns: Array - Array of tree items with structure: {name, type, children?}, or empty array if root doesn’t exist

function/get-gravatar.html

Get Gravatar URL.

Parameters:

Example:

1

{{- $gravatar := dict "Email" "user@example.com" "Size" "32" | partial "function/get-gravatar.html" -}}

function/get-remote-image.html

Cache remote image locally.

function/get-remote-json.html

Fetch and parse remote JSON with daily caching.

Parameters:

Returns: Object - The parsed JSON response, or empty dict on failure

function/get-taxonomy-icon.html

Resolve taxonomy icon by slot with site-level overrides.

Parameters:

Returns: String - Icon class

function/id.html

ID.

function/is-cjk.html

Check if the current page language is CJK (Chinese, Japanese, or Korean).

Returns: Boolean - True if the page language is CJK

function/is-url-remote.html

Check if a parsed URL is remote (has both scheme and host).

Parameters:

Returns: Boolean - True if the URL has a non-empty scheme and host

function/js-build.html

Build and minify a JS resource with unified behavior.

Parameters:

Returns: resource.Resource

function/logical-direction.html

Normalize a direction value to CSS logical direction.

Converts legacy “left”/“right” values to “start”/“end”. Valid values (“start”/“end”) are returned as-is.

Parameters:

Returns: String - The normalized logical direction (“start” or “end”), defaults to “start” for unknown values

function/marked-text.html

Marked texts rendering This is an experimental syntax highlighting for the marked texts. Embed types: default, primary, secondary, success, warning, danger.

function/param.html

Get a page-level section param with shorthand support and site defaults merged.

Handles shorthand booleans in front matter (e.g., toc: true) by wrapping them in a dict with an “enable” key, then merges with site-level defaults.

For Page-level scalar params (e.g., capitalize_titles, ruby, password), use .Param “xxx” directly instead of this partial.

Parameters:

Returns: Map - The merged param map

Example:

1
2

{{- $toc := dict "Page" . "Key" "toc" | partial "function/param.html" -}}
{{- $config := dict "Page" . "Key" "math" "ToCamel" true | partial "function/param.html" -}}

function/path.html

https://discourse.gohugo.io/t/how-decode-urls-in-hugo/7549/4.

function/resource.html

Resolve a Hugo resource by path.

Attempts to find the resource from page resources first, then global resources. Returns 0 if the resource is not found.

Parameters:

Returns: resource.Resource|Number - The resolved resource, or 0 if not found

function/ruby.html

Ruby.

function/scss-vars.html

Build the complete SCSS variables dict passed to toCSS as hugo:vars. Two categories:

• Internal: theme config (base URL, logo, loading image) — highest priority
• Appearance: defaults + derived + user config ([params.appearance])

Reference: assets/scss/_variables.scss Note: Color values must use hex format (e.g. “#ff0000”), CSS named colors (e.g. “red”) are not supported because Hugo’s isTypedCSSValue only recognizes hex colors, CSS functions, and CSS units.

function/suffix-validation.html

Validate if the given path has a valid suffix.

Example:

1
2

{{- $suffixList := slice ".jpeg" ".jpg" ".png" ".gif" ".bmp" ".tif" ".tiff" ".webp" ".avif" ".svg" -}}
{{- $suffixValid := (dict "Path" .Path "Suffixes" $suffixList | partial "function/suffix-validation.html") -}}

function/task-lists.html

Task lists rendering.

function/to-css.html

Compile SCSS to CSS via dartsass, optionally minify and fingerprint.

Parameters:

Returns: resource.Resource

function/trim.html

Trim whitespace from the beginning and end of a string.

function/xml-content.html

Process content for XML output (used in RSS feeds).

Applies content transformations (ruby, fraction, Font Awesome) and prepends the featured image, then XML-escapes the result.

Parameters:

Returns: String - The XML-escaped processed content

gen/

Generated or config output partials.

2 partials

gen/config.html

Generate per-page runtime config as window.config JS content.

Parameters:

Returns: string - The JS content string (window.config=<JSON>;)

gen/mermaid-bootstrap.html

Mermaid bootstrap script generator. Returns inline module JS source used by store/script.html. Config is read from window.config.mermaid at runtime.

Parameters:

home/

Homepage-specific partials.

1 partial

home/profile.html

Homepage profile section partial.

Renders the homepage hero area with avatar, title, subtitle (with optional TypeIt animation), social links, and disclaimer text.

Called from: layouts/index.html.

init/

Theme initialization partials (version, environment detection, compatibility, global setup).

8 partials

init/compatibility.html

Browser compatibility polyfills partial.

Conditionally loads polyfill.io and object-fit-images for older browsers based on site compatibility configuration.

init/detection-deprecated.html

Deprecated parameter detection.

init/detection-encryption.html

Encrypted pages detection partial.

Scans all regular pages for password-protected content and emits a build-time warning listing encrypted pages with their titles and permalinks.

init/detection-env.html

FixIt theme environment detection.

init/detection-pagefind.html

Pagefind search index detection partial.

Warns at build time if Pagefind search is enabled but the index file is missing from the public/ directory.

init/detection-version.html

Version detection and update checking partial.

Validates Hugo minimum version, detects the FixIt theme version from params, warns about dev versions, and optionally checks for newer releases via the GitHub API.

init/global.html

Global initialization partial.

Merges translations, resolves main section pages, stores them for cross-partial access, and sets up the GitHub API token header from the HUGO_PARAMS_GHTOKEN environment variable.

init/index.html

Theme initialization entry point partial.

Sets the theme version and orchestrates all init sub-partials: environment detection, version checking, deprecated param detection, Pagefind index check, encryption warnings, global setup, and browser compatibility.

Called from: layouts/baseof.html.

plugin/

Third-party plugin integration partials.

20 partials

plugin/admonition.html

Admonition box rendering partial.

The extended syntax of alert is compatible with Obsidian and FixIt admonition shortcode.

Parameters:

plugin/alert.html

The basic syntax of alert is compatible with GitHub, Obsidian, and Typora.

Parameters:

Example:

1

{{- dict "Text" .Text "Type" .AlertType "Attributes" .Attributes | partial "plugin/alert.html" -}}

plugin/analytics.html

Analytics script injector.

• Reads analytics config from Site Store.
• Conditionally renders provider snippets when enabled.
• Supported providers include Google, Fathom, Baidu, Umami, and others.

Parameters:

plugin/code-block-wrapper.html

Code block wrapper hook for highlight output.

• Applies wrapper UI features based on codeblock config.
• Supports classic/modern modes, copy button, expand button, and line-number states.

Parameters:

plugin/diagram-copy-btn.html

Copy button for diagram-like plugins.

Parameters:

plugin/echarts.html

ECharts rendering partial for code fences extended syntax and shortcode usage.

• Skips rendering when MarkupScope is home.
• Supports chart options from inline content, data key, or resource file.
• Supports JavaScript template mode via js/file options.

Parameters:

plugin/file-tree.html

Recursive function to render tree from structured data.

Parameters:

plugin/fixit-encryptor.html

Encrypted content renderer.

• Renders template placeholder for post-build AES-256-GCM encryption.
• Supports full-page mode and partial mode with isolated target container.

Parameters:

plugin/icon.html

Icon renderer for Font Awesome classes and SVG sources.

• Renders <i> element when .Class is provided.
• Resolves local SVG resources or external SVG URL fallback.
• Supports Simple Icons shorthand by icon name.

Parameters:

plugin/image.html

Image resource plugin. Handles page resources, global resources, and remote images. Supports optimisation, srcset generation, black list filtering, and remote caching.

Pass .Page when the caller needs page-level config override (e.g., content images). Omit .Page for decorative/site-level images (e.g., logos, avatars, badges).

Parameters:

Example:

1
2
3
4

{{- dict "Src" "cover.jpg" "Resources" .Resources | partial "plugin/image.html" -}}
{{- dict "Src" "logo.png" "Class" "logo" "Width" 32 "Height" 32 | partial "plugin/image.html" -}}

Thanks @HEIGE-PCloud for the original code in the DoIt theme.

plugin/link.html

Link rendering partial for regular and card-style links.

• Auto-detects external links and applies target/rel policies.
• Supports optional icon, download hint, and external icon display.
• Supports card mode with URL meta and favicon fallback.

Parameters:

plugin/mermaid.html

Mermaid rendering partial for code fences extended syntax and shortcode usage.

• Skips rendering when MarkupScope is home.
• Supports wrapped view with tabs/actions and plain diagram mode.
• Supports per-diagram filename for code/download actions.

Parameters:

plugin/pagefind-metadata.html

Pagefind search metadata injection partial.

Outputs meta tags for Pagefind indexing: hidden/encrypted filters, date/title sorting fields, and tag/category/collection metadata. Only active when Pagefind search is enabled and the current context is a page.

plugin/post-chat-ai.html

PostChat AI service. PostChat: https://ai.zhheo.com/docs/addCode.html PostSummary: https://ai.zhheo.com/docs/summary.html Podcast: https://ai.zhheo.com/docs/podcast.html TODO refactor and migrate to theme component.

plugin/reward.html

Post reward panel renderer.

• Renders reward switch button and reward QR/payment images.
• Supports optional author prefix and animation mode.

Parameters:

plugin/script.html

Script tag renderer.

• Accepts direct script HTML, a pre-built resource, or builds from source path.
• Supports template execution, minify/build/fingerprint pipeline, and extra attrs.

Parameters:

plugin/share.html

Social share buttons renderer.

• Reads share switches from merged theme/page params.
• Outputs provider-specific sharer attributes for supported platforms.

Parameters:

plugin/social.html

Social profile link helper.

• Builds destination from explicit URL or from Prefix/Template/Id.
• Delegates final rendering to plugin/link.html with rel=me.

Parameters:

plugin/style.html

Stylesheet tag renderer.

• Accepts direct <link> HTML, a pre-built resource, or builds from source path.
• Supports template execution, optional toCSS, minify/fingerprint, and preload mode.

Parameters:

plugin/timeline.html

Timeline rendering partial for code fences extended syntax and shortcode usage.

• Supports events from inline content, data key, resource file, or direct Events input.
• Supports reverse order, placement, animation, node style, and size options.

Parameters:

section/

Section-level partials.

1 partial

section/recently-updated.html

Recently updated pages for archives, section and term list.

single/

Single-post page partials.

13 partials

single/aside-collection.html

Sidebar Collection.

single/aside-toc.html

Sidebar Table of Contents.

single/collection-list.html

Collection List.

single/collection-nav.html

Collection Navigation.

single/disclaimer.html

Post disclaimer/declaration partial.

Displays a lightweight disclaimer notice at the beginning of an article. Supports multiple types: ai, ai-assisted, ai-translated, repost, original, custom. The “custom” type requires content to be specified, otherwise it will not be displayed.

single/expiration-reminder.html

Content expiration reminder partial.

Displays a note or warning admonition when the page’s last modification date exceeds configurable day thresholds (default: 90 days for note, 180 days for warning). Skipped for password-protected pages.

single/footer.html

Git info.

single/nav-dialog.html

Nav Dialog - Mobile drawer for TOC and Collections.

single/post-author.html

Post author display partial.

Renders the author name with optional avatar and link. Stores the resolved author map in the page store for use by other partials.

single/post-included-in.html

Post categories and collections display partial.

Renders category and collection links with icons for the current page. Displays categories only, collections only, or both depending on which are present.

single/related-aside.html

Related Content.

single/related.html

Related Content.

single/reward.html

Post reward/donation panel partial.

Reads the reward config from front matter and site defaults, then delegates rendering to plugin/reward.html.

store/

Asset accumulation store partials.

2 partials

store/script.html

Script accumulation store partial.

Appends a script resource entry to the page’s accumulated script list. Used by other partials to register JS assets that are rendered together at the end of the page via base/assets.html.

store/style.html

Style accumulation store partial.

Appends a style resource entry to the page’s accumulated style list. Used by other partials to register CSS assets that are rendered together in the head section via base/assets.html.

(root)

1 partial

custom.html

Custom partial block definitions.

Defines named template blocks (custom-head, custom-menu, custom-profile, custom-aside, custom-comment, custom-footer, custom-widgets, custom-assets, custom-post__toc, custom-post__content, custom-post__footer) that users can extend via the custom_partials configuration.