Hugo-only features on pydata-hugo-theme

Asset pipeline

Mon, 01 Jan 0001 00:00:00 +0000

The FontAwesome and Bootstrap JS mounted via [[module.mounts]] (see Hugo Modules ) are loaded through Hugo Pipes , not referenced as plain static <script src> tags:

{{- with resources.Get "vendor/fontawesome/all.min.js" }}
 {{- if hugo.IsDevelopment }}
 <script src="{{ .RelPermalink }}" defer></script>
 {{- else }}
 {{- with . | fingerprint }}
 <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous" defer></script>
 {{- end }}
 {{- end }}
{{- end }}

In development builds, the file is served as-is for fast rebuilds. In production builds (hugo --minify, or whenever hugo.IsDevelopment is false), it’s fingerprinted — Hugo computes a content hash, appends it to the URL for cache-busting, and adds a Subresource Integrity (integrity) attribute the browser verifies before executing the script. Sphinx has no equivalent — static files there are referenced as-is, with no build-time hashing or integrity verification.

Content-Security-Policy

Mon, 01 Jan 0001 00:00:00 +0000

head.html emits a <meta http-equiv="Content-Security-Policy"> tag on every page, with script-src already covering the CDNs the theme’s own search feature needs (cdnjs for FontAwesome, jsdelivr for Fuse.js). If your site embeds a third-party iframe (a calendar widget, a video embed, etc.), extend frame-src via:

[params]
 csp_frame_src = ['https://calendar.google.com']

'self' is always included automatically — you only need to list additional origins. Upstream Sphinx docs don’t ship a CSP meta tag at all; this is engineering specific to this port.

Hugo Modules

Mon, 01 Jan 0001 00:00:00 +0000

This is the mechanism the theme itself is distributed through — Sphinx has no equivalent concept (a Sphinx theme is just a Python package with a theme.conf, not a versioned, mountable dependency graph).

Explicit mounts

Adding any [[module.mounts]] entry disables Hugo’s implicit default mounts, so this module’s hugo.toml re-declares every standard component directory explicitly (content, static, layouts, data, assets, i18n, archetypes), plus two npm-sourced mounts that pull prebuilt JS straight out of node_modules into the asset pipeline:

Markdown render hooks

Mon, 01 Jan 0001 00:00:00 +0000

layouts/_default/_markup/render-link.html is a Hugo render hook — it intercepts every [text](url) link Hugo renders from your Markdown content, site-wide, and applies the same external_links new-tab/exceptions rules (see Header links ) that the theme’s own hand-written partials use.

The practical effect: you never need to write target="_blank" rel="noopener" by hand in a blog post or page — every content-authored link gets consistent external-link behavior automatically, driven by one site-wide config block.

Menus

Mon, 01 Jan 0001 00:00:00 +0000

Sphinx derives navigation from the doc tree (toctree directives) — there’s no separately configured menu structure. This port instead uses two independent Hugo menus:

site.Menus.main — top navbar links (rendered by navbar-nav.html), with automatic overflow into a “More” dropdown past header_links_before_dropdown entries (see Header links ).
site.Menus.sidebar — the left sidebar nav tree (rendered by sidebar-nav.html, see Sidebar navigation ), falling back to site.Menus.main if you don’t define one.

Because they’re independent, your top nav and sidebar nav don’t have to mirror each other — a common pattern (used by this docs site itself) is a short main menu (just “Docs” + “GitHub”) alongside a much deeper sidebar menu for in-page navigation.

Per-page overrides

Mon, 01 Jan 0001 00:00:00 +0000

Several slot/behavior params can be overridden on a single page via frontmatter, resolved through a page → site → hardcoded-default fallback chain (.Params.x | default (site.Params.x | default fallback)):

---
title: A page with no right sidebar
show_toc: false
---

show_toc (see Page table of contents ) overrides secondary_sidebar_items for just that page, without touching the site-wide default. show_prev_next works the same way, overriding the site-wide show_prev_next param (default true) to hide (or show) the prev/next footer links on a single page — useful for standalone pages like an event calendar or an RSS feed list, where “previous/next page in section” links don’t make sense: