chore: tidy templates, add comments

layouts/_default/search.html

@@ -35,6 +35,14 @@ <h1 class="py-4">{{ .Title }}</h1>
     window.addEventListener("load", async function () {
       // Hydrate pagefind
       pagefind = await import("/pagefind/pagefind.js");
+      await pagefind.options({
+        ranking: {
+          termFrequency: 0.2,
+          pageLength: 0.75,
+          termSaturation: 1.4,
+          termSimilarity: 6.0,
+        },
+      });
 
       // Get the query parameter from the URL
       const urlParams = new URLSearchParams(window.location.search);

layouts/index.metadata.json

@@ -1,6 +1,6 @@
 [
 {{- range where site.Pages "Params.sitemap" "!=" false -}}
-  {{- $title := partialCached "utils/title.html" . . -}}
+  {{- $title := .LinkTitle -}}
   {{- $desc := partialCached "utils/description.html" . . -}}
   {{- $kwd := partialCached "utils/keywords.html" . . -}}
   {{- $tags := slice -}}

layouts/index.redirects.json

@@ -1,3 +1,25 @@
+{{- /*
+
+  This template generates the redirects.json file used to generate 301
+  redirects in production. It takes all the redirects defined in
+  data/redirects.yml, as well as all the aliases defined in front matter, and
+  outputs a simple key-value JSON file:
+
+  {
+    "<request-path>": "<redirect-path>",
+    ...
+  }
+
+  e.g.
+
+  {
+    "/engine/reference/builder/": "/reference/dockerfile/",
+    ...
+  }
+
+  */
+-}}
+
 {{- $redirects := newScratch }}
 {{- range $i, $e := site.AllPages -}} 
   {{- if .Params.aliases -}}

layouts/index.robots.txt

@@ -1,3 +1,9 @@
+{{- /*
+	For Netlify deployments, we disallow all routes to prevent search
+	engines from indexing our preview sites.
+	*/
+-}}
+
 {{- if hugo.IsProduction -}}
 User-agent: *
 

layouts/partials/github-links.html

@@ -1,3 +1,8 @@
+{{- /*
+  Adds links for editing the page or requesting changes:
+  - "Edit this page": Only in production, skips files from `_vendor/` (upstream repositories).
+  - "Request changes": Links to a pre-filled issue form.
+*/ -}}
 {{ if hugo.IsProduction }}
 {{ with .File }}
 {{ if not (in .Filename "/_vendor/") }}

layouts/partials/head.html

@@ -1,16 +1,5 @@
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<script type="module">
-const pagefind = await import("/pagefind/pagefind.js");
-await pagefind.options({
-  ranking: {
-    termFrequency: 0.2,
-    pageLength: 0.75,
-    termSaturation: 1.4,
-    termSimilarity: 6.0,
-  },
-});
-</script>
 {{ partial "meta.html" . }}
 {{- if hugo.IsProduction -}}
   <script

layouts/partials/meta.html

@@ -1,10 +1,9 @@
-{{ $title := partial "utils/title.html" . }}
 {{ $description := partial "utils/description.html" . }}
 {{ if .IsHome }}
   <title>{{ site.Title }}</title>
 {{ else }}
   <title>
-    {{ printf "%s | %s" $title site.Title }}
+    {{ printf "%s | %s" .LinkTitle site.Title }}
   </title>
 {{ end }}
 {{ if or (eq .Params.sitemap false) (not hugo.IsProduction) }}
@@ -22,7 +21,7 @@
 <meta name="theme-color" content="#2496ed" />
 
 <!-- SEO -->
-<meta name="twitter:title" itemprop="title name" content="{{ $title }}" />
+<meta name="twitter:title" itemprop="title name" content="{{ .LinkTitle }}" />
 <meta
   name="twitter:description"
   property="og:description"
@@ -38,7 +37,7 @@
   content="{{ (resources.Get "images/thumbnail.webp").Permalink }}"
 />
 <meta name="twitter:image:alt" content="Docker Documentation" />
-<meta property="og:title" content="{{ $title }}" />
+<meta property="og:title" content="{{ .LinkTitle }}" />
 <meta property="og:description" content="{{ $description }}" />
 <meta property="og:type" content="website" />
 <meta
@@ -59,4 +58,4 @@
   itemprop="datePublished"
   content="{{ .PublishDate | default .Lastmod }}"
 />
-  <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","headline":{{ $title | jsonify }},"description":{{ $description | jsonify }},"url":"{{ .Permalink }}"}</script>
+  <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","headline":{{ .LinkTitle | jsonify }},"description":{{ $description | jsonify }},"url":"{{ .Permalink }}"}</script>

layouts/partials/pagemeta.html

@@ -1,3 +1,10 @@
+{{- /*
+  Renders a table of contents (ToC) for the page.
+  - Uses `.Fragments.Headings` to generate a nested ToC if headings exist and `notoc` is not set to `true`.
+  - Limits heading levels to a min and max range (`$min` and `$max`).
+  - Wraps the ToC in a `data-pagefind-ignore` container to exclude it from search indexing.
+  - Includes a recursive template (`walkHeadingFragments`) to handle nested headings.
+*/ -}}
 {{- $toc := false }}
 {{- with .Fragments }}
   {{- $toc = and (ne page.Params.notoc true) .Headings }}

layouts/partials/search-bar.html

@@ -43,6 +43,14 @@
   <script type="module">
     window.addEventListener("load", async function () {
       const pagefind = await import("/pagefind/pagefind.js");
+      await pagefind.options({
+        ranking: {
+          termFrequency: 0.2,
+          pageLength: 0.75,
+          termSaturation: 1.4,
+          termSimilarity: 6.0,
+        },
+      });
 
       const searchBarInput = document.querySelector("#search-bar-input");
       const searchBarResults = document.querySelector(

layouts/partials/sidebar/guides.html

@@ -1,3 +1,11 @@
+{{- /*
+  Renders a sidebar for pages in the `/guides` section.
+  - Detects if the current page is part of a multipage guide (`.Store.Set "multipage"`).
+  - Displays the section's title, summary, languages, tags, and estimated time (`Params.time`).
+  - Includes a stepper navigation (`guides-stepper.html`) for multipage guides.
+  - Optionally lists resource links from `Params.resource_links`.
+  - Provides a link back to the main `/guides/` index.
+*/ -}}
 <div class="flex flex-col gap-4 px-4 pt-2">
   {{- $root := . }}
   {{- .Store.Set "multipage" false }}

layouts/partials/sidebar/mainnav.html

@@ -1,3 +1,9 @@
+{{- /*
+  Complements the section-specific sidebar navigation.
+  - Renders the main navigation for site sections, linking to the current or ancestor section/page.
+  - Uses the `site.Menus.main` configuration to determine primary navigation structure.
+  - Toggles visibility of nested menu items for the main sections.
+*/ -}}
 <!-- Main navigation for the sidebar -->
 <div class="py-2 px-4" x-data="{ expanded: false }">
   <div class="flex w-full items-center justify-between">

layouts/partials/sidebar/sections.html

@@ -1,3 +1,11 @@
+{{- /*
+  This template recursively renders the sidebar navigation, grouping pages by `Params.sidebar.groups`.
+  Highlights:
+  - Supports hierarchical navigation with collapsible sections (`renderList` template).
+  - Dynamically applies current page highlighting and expanded states.
+  - Handles external links via `Params.sidebar.goto` in `renderSingle`.
+  - Requires `Params.sitemap` and `Params.sidebar` for filtering and behavior.
+*/ -}}
 <!-- section tree -->
 <nav class="md:text-sm flex flex-col">
   <div

layouts/partials/sidebar/tags.html

@@ -1,3 +1,8 @@
+{{- /*
+  Renders a flat list of tags for the "tags" taxonomy.
+  - Unlike `sections.html`, this template is based on taxonomy terms, not section pages.
+  - Highlights the current tag page and links to all tag pages.
+*/ -}}
 <ul class="md:text-sm">
   {{- range site.Taxonomies.tags }}
     <li class="pl-4 hover:text-blue-light hover:dark:text-blue-dark

layouts/partials/tooltip.html

@@ -1,3 +1,7 @@
+{{- /*
+  Renders a tooltip component using Floating UI for positioning.
+  See script at `assets/js/src/tooltip.js` for functionality.
+*/ -}}
 <div data-tooltip-wrapper>
   <div data-tooltip-button class="icon-svg flex items-center text-blue-light dark:text-blue-dark">
     {{ partialCached "icon" "help" "help" }}

layouts/partials/utils/css.html

@@ -1,3 +1,8 @@
+{{- /*
+  Processes and links the main CSS file (`assets/css/styles.css`).
+  - Applies PostCSS, minification, fingerprinting, and post-processing in production.
+  - Adds inline CSS to hide injected images in production builds.
+*/ -}}
 {{ $styles := resources.Get "css/styles.css" }}
 {{ $styles = $styles | css.PostCSS }}
 {{ if hugo.IsProduction }}

layouts/partials/utils/description.html

@@ -1,3 +1,9 @@
+{{- /*
+  Utility template to extract a description for the current page.
+  - Prioritizes `.Description` or falls back to front matter in `site.Data.frontmatter`.
+  - Replaces newlines with spaces and trims trailing spaces.
+  - Designed for reuse via `partial` calls to generate meta descriptions or similar content.
+*/ -}}
 {{ $desc := "" }}
 {{ if .Description }}
   {{ $desc = strings.Replace .Description "\n" " " }}

layouts/partials/utils/keywords.html

@@ -1,3 +1,9 @@
+{{- /*
+  Utility template to extract keywords for the current page.
+  - Uses `.Keywords` if available or falls back to front matter in `site.Data.frontmatter`.
+  - Cleans and trims keywords, joining them into a comma-separated string.
+  - Intended for reuse in meta tags or other keyword-based contexts.
+*/ -}}
 {{ $keywords := "" }}
 {{ if .Keywords }}
   {{ $keywords = collections.Apply .Keywords "strings.Trim" "." ", " }}

layouts/sitemap.xml

@@ -1,3 +1,8 @@
+{{- /*
+  Requires the file `static/sitemap.xsl` to exist for the XSL styling to work.
+  If missing, the sitemap will lack the associated styling.
+  */
+-}}
 {{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
 {{ printf "<?xml-stylesheet type=\"text/xsl\" href=\"%s\"?>" (urls.AbsURL "sitemap.xsl") | safeHTML }}
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

tailwind.config.js

@@ -43,12 +43,6 @@ module.exports = {
           },
         },
       }),
-
-      gridTemplateColumns: {
-        'main-xl': 'minmax(300px, 1fr) minmax(100ch, 1fr) 1fr',
-        'main-lg': '300px minmax(75ch, 2fr) 1fr',
-        'main-md': '250px 1fr',
-      },
     },
 
     // theme values