Partial Docstrings

Hugo Partial Docstrings

Hugo template comments can carry lightweight implementation docs directly next to the partial they describe. The docs site can surface the first template comment block from a file with partial-doc, or scan one directory with partial-docs.

Use this for stable interface notes: accepted dict keys, return shape, ordering constraints, or ownership boundaries. Do not put long architecture guides only inside partial comments; keep those in normal docs pages and use docstrings as the local source of truth for small API contracts.

Examples

layouts/partials/views/summaries.html

summary.html partial documentation

This partial renders a list of page summaries, sorted by shared ordered-page logic, slug, or date.

Sorting: • ordered mode (default): uses shared ordered-pages logic: weight first, then front matter date, then file modification time. • slug mode: orders all pages by the base name of .RelPermalink. • date mode: - pages are sorted by Date descending.

Implementation: 1. Builds a slice of dicts: each dict contains: - Page: the Page object - Name: basename of .RelPermalink 2. Depending on .Params.Summaries.sort (“ordered”, “slug”, or “date”), computes the final $pages slice. 3. Loops over $pages, setting: - loading: “eager” for the first item, “lazy” for others. - class: CSS classes for first, even, odd items (using .Params.Summaries.first, .right, .left). 4. Merges global .Params.Summaries into each dict and invokes the “views/summary” partial.

Parameters (merged into $dict for partial “views/summary”): - Page *Page : The Hugo Page object being rendered. - class string : CSS classes for summary container. - loading string : Image loading attribute (“eager” or “lazy”). - first string : CSS classes for the first summary. - right string : CSS classes for summaries with even index (excluding first). - left string : CSS classes for summaries with odd index (excluding first). - summary bool : Show or hide summary text. - authors bool : Show or hide authors list. - date bool : Show or hide date. - figure bool : Wrap thumbnail in a

element. - timeFormat string : Go time.Format layout for displaying dates. - width int : Width in pixels for thumbnail images.

layouts/partials/media/render.html

partials/media/render.html Single entry point for all media. Accepts: dict{ “Destination”: string “Title”: string “Text”: string “Page”: .Page “Layout”: “left”|“right”|“fit” “NoLink”: bool “Image”: .Resource (optional) “ForceType”: string (optional; e.g. “iframe” to bypass file-extension detection) }

Notes:

layouts/partials/head/import/runtime-core.html

Critical runtime/editor imports. Keep these explicit and ordered. Site overrides should import this partial rather than hand-rolling core JS tags.

Directory Scan

layouts/partials/views

layouts/partials/views/latest.html

This partial is called by _default/list.html In the future, this could be called elsewhere, such as sidebar or home as a featured article @first: class attributes @right: class attributes @left: class attributes @summary: bool @authors: bool @date: bool @figure: bool @timeFormat: timeFormat @width: int @title: string

layouts/partials/views/summaries.html

summary.html partial documentation

This partial renders a list of page summaries, sorted by shared ordered-page logic, slug, or date.

Sorting: • ordered mode (default): uses shared ordered-pages logic: weight first, then front matter date, then file modification time. • slug mode: orders all pages by the base name of .RelPermalink. • date mode: - pages are sorted by Date descending.

Implementation: 1. Builds a slice of dicts: each dict contains: - Page: the Page object - Name: basename of .RelPermalink 2. Depending on .Params.Summaries.sort (“ordered”, “slug”, or “date”), computes the final $pages slice. 3. Loops over $pages, setting: - loading: “eager” for the first item, “lazy” for others. - class: CSS classes for first, even, odd items (using .Params.Summaries.first, .right, .left). 4. Merges global .Params.Summaries into each dict and invokes the “views/summary” partial.

Parameters (merged into $dict for partial “views/summary”): - Page *Page : The Hugo Page object being rendered. - class string : CSS classes for summary container. - loading string : Image loading attribute (“eager” or “lazy”). - first string : CSS classes for the first summary. - right string : CSS classes for summaries with even index (excluding first). - left string : CSS classes for summaries with odd index (excluding first). - summary bool : Show or hide summary text. - authors bool : Show or hide authors list. - date bool : Show or hide date. - figure bool : Wrap thumbnail in a

element. - timeFormat string : Go time.Format layout for displaying dates. - width int : Width in pixels for thumbnail images.

layouts/partials/views/summary.html

views/summary.html

Renders one summary card for a page in list/section output.

Inputs:

  • Page: page to summarize.
  • path: optional page path relative to the current page.
  • optional flags: summary, authors, date, figure, listChildren, childrenOpen, childrenTitle.
  • optional presentation keys: timeFormat, width, loading, class, title, bookIndex.

Summary source priority:

  1. front matter summary;
  2. front matter description;
  3. front matter abstract;
  4. Hugo .Summary;
  5. plain page text.

This priority keeps docs wrapper cards from exposing raw shortcode/JSON output when front matter already provides a concise description.