docs(layouts): add header comments to undocumented partials

Add `{{/* ... */}}` header comments to 25 partials that had no documentation,
enabling `pnpm gen:docs` to generate their reference docs. Also fix
base/head/index.html leading blank line that prevented parser matching.

Groups covered: base/, feed/, function/, home/, init/, plugin/, single/, store/, (root).

layouts/_partials/base/breadcrumb.html

@@ -1,3 +1,12 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- if (gt (len .Ancestors.Reverse) 1) | and (eq .Site.Params.breadcrumb.enable true) -}}
   {{- $separator := .Site.Params.breadcrumb.separator | default "/" -}}
   <nav aria-label="breadcrumb" class="breadcrumb-container{{ if .Site.Params.breadcrumb.sticky }} sticky{{ end }}">

layouts/_partials/base/comment.html

@@ -1,3 +1,13 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $cdn := .Site.Store.Get "cdn" | default dict -}}
 {{- $fingerprint := .Site.Store.Get "fingerprint" -}}
 {{- $comment := .Store.Get "comment" | default dict -}}

layouts/_partials/base/footer.html

@@ -1,3 +1,16 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $footerConfig := .Site.Params.footer -}}
 
 {{- if ne $footerConfig.enable false -}}

layouts/_partials/base/head/index.html

@@ -1,4 +1,3 @@
-
 {{- /*
   Head Partial - Comprehensive head section template
 

layouts/_partials/base/header.html

@@ -1,3 +1,15 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $buildDrafts := .Page.Draft -}}
 {{- $relLangURL := relLangURL "" -}}
 

layouts/_partials/base/paginator.html

@@ -1,3 +1,10 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- if gt .Paginator.TotalPages 1 -}}
   <ul class="pagination">
     {{- .Site.Store.Set "paginator.ellipsed" false -}}

layouts/_partials/base/widgets.html

@@ -1,3 +1,18 @@
+{{- /*
+  Global widget layer partial.
+
+  Renders floating UI elements across all pages:
+  - Fixed action buttons (back-to-top, TOC drawer, view comments)
+  - GitHub corner link
+  - Search dialog modal
+  - Reading progress bar
+  - Link guard confirmation dialog
+  - Service worker update notification
+  - Noscript warning
+
+  Called from: layouts/baseof.html.
+*/ -}}
+
 <div class="widgets">
   {{- $backToTop := .Site.Params.back_to_top -}}
   {{- $comment := .Store.Get "comment" -}}

layouts/_partials/custom.html

@@ -1,3 +1,12 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- define "custom-head" -}}
   {{- $ctx := . -}}
   {{- range .Site.Params.custom_partials.head -}}

layouts/_partials/feed/rss.html

@@ -1,3 +1,11 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $pages := .Pages -}}
 {{- /* Front matter: password */ -}}
 {{- $pages = where $pages "Params.password" "eq" nil -}}

layouts/_partials/function/content.html

@@ -1,3 +1,16 @@
+{{- /*
+  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.
+
+  @param {String} .Content - The raw HTML content
+  @param {Boolean} [.Ruby] - Whether to process ruby annotations
+  @param {Boolean} [.Fraction] - Whether to process fraction syntax
+  @param {Boolean} [.Fontawesome] - Whether to process Font Awesome shortcodes
+  @return {String} The processed content
+*/ -}}
+
 {{- $content := .Content -}}
 
 {{- if $content -}}

layouts/_partials/function/get-remote-json.html

@@ -1,3 +1,11 @@
+{{- /*
+  Fetch and parse remote JSON with daily caching.
+
+  @param {String} .URL - The remote JSON URL (required)
+  @param {Object} [.OPTIONS] - Additional options for resources.GetRemote
+  @return {Object} The parsed JSON response, or empty dict on failure
+*/ -}}
+
 {{- $response := dict -}}
 {{- $url := .URL -}}
 {{- $options := .OPTIONS | default dict -}}

layouts/_partials/function/is-cjk.html

@@ -1,3 +1,9 @@
+{{- /*
+  Check if the current page language is CJK (Chinese, Japanese, or Korean).
+
+  @return {Boolean} True if the page language is CJK
+*/ -}}
+
 {{- $cjk := slice "zh-cn" "zh-tw" "ja" "ko" -}}
 {{- $isCJK := (in $cjk .Page.Language.Name) | default .Page.Params.IsCJKLanguage -}}
 

layouts/_partials/function/is-url-remote.html

@@ -1 +1,8 @@
+{{- /*
+  Check if a parsed URL is remote (has both scheme and host).
+
+  @param {Object} . - A parsed URL object (from urls.Parse)
+  @return {Boolean} True if the URL has a non-empty scheme and host
+*/ -}}
+
 {{- return and (not (eq .Scheme "")) .Host -}}

layouts/_partials/function/resource.html

@@ -1,3 +1,14 @@
+{{- /*
+  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.
+
+  @param {String} .Path - The resource path (page resource or global resource)
+  @param {Object} [.Resources] - Page resources collection
+  @return {resource.Resource|Number} The resolved resource, or 0 if not found
+*/ -}}
+
 {{- $Resources := .Resources | default page.Resources -}}
 {{- $resource := 0 -}}
 {{- $url := urls.Parse .Path -}}

layouts/_partials/function/xml-content.html

@@ -1,3 +1,17 @@
+{{- /*
+  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.
+
+  @param {String} .Content - The raw HTML content
+  @param {Boolean} [.Ruby] - Whether to process ruby annotations
+  @param {Boolean} [.Fraction] - Whether to process fraction syntax
+  @param {Boolean} [.Fontawesome] - Whether to process Font Awesome shortcodes
+  @param {String} [.FeaturedImage] - Featured image URL to prepend
+  @return {String} The XML-escaped processed content
+*/ -}}
+
 {{- $content := .Content -}}
 
 {{- if $content -}}

layouts/_partials/home/profile.html

@@ -1,3 +1,12 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $profile := .Site.Params.home.profile -}}
 {{- $author := partial "function/get-author-map.html" .Params.author -}}
 

layouts/_partials/init/compatibility.html

@@ -1,3 +1,10 @@
+{{- /*
+  Browser compatibility polyfills partial.
+
+  Conditionally loads polyfill.io and object-fit-images for older browsers
+  based on site compatibility configuration.
+*/ -}}
+
 {{- $compatibility := .Site.Params.compatibility | default dict -}}
 {{- $cdn := .Site.Store.Get "cdn" | default dict -}}
 {{- $fingerprint := .Site.Store.Get "fingerprint" -}}

layouts/_partials/init/detection-encryption.html

@@ -1,3 +1,10 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $encryptedPages := slice -}}
 {{- range .Site.RegularPages -}}
   {{- if or .Params.password (.Store.Get "hasEncryptor") -}}

layouts/_partials/init/detection-pagefind.html

@@ -1,3 +1,10 @@
+{{- /*
+  Pagefind search index detection partial.
+
+  Warns at build time if Pagefind search is enabled but the index file
+  is missing from the public/ directory.
+*/ -}}
+
 {{- if and .Site.Language.IsDefault .Site.Params.search.enable (eq .Site.Params.search.type "pagefind") (not (fileExists "public/pagefind")) -}}
   {{- warnf "[FixIt] Pagefind search index not found.\nRun `npx pagefind --site public` in the site root directory after building.\n" -}}
 {{- end -}}

layouts/_partials/init/detection-version.html

@@ -1,3 +1,11 @@
+{{- /*
+  Version detection and update checking partial.
+
+  Validates Hugo minimum version, checks Hugo Extended edition, detects the
+  FixIt theme version from params, warns about dev versions, and optionally
+  checks for newer releases via the GitHub API.
+*/ -}}
+
 {{- $version := hugo.Store.Get "version" -}}
 {{- $latest := $version -}}
 {{- $devOpts := .Site.Store.Get "devOpts" -}}

layouts/_partials/init/global.html

@@ -1,3 +1,11 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $pages := .Site.RegularPages }}
 
 {{- /* Merge missing translations from other languages */ -}}

layouts/_partials/init/index.html

@@ -1,4 +1,14 @@
-{{- hugo.Store.Set "version" "v1.0.0-mrudz3q9" -}}
+{{- /*
+  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.
+*/ -}}
+
+{{- hugo.Store.Set "version" "v1.0.0-mrx1h9pi" -}}
 {{- .Store.Set "this" dict -}}
 
 {{- partial "init/detection-env.html" . -}}

layouts/_partials/plugin/admonition.html

@@ -1,5 +1,6 @@
-
 {{- /*
+  Admonition box rendering partial.
+
   The extended syntax of alert is compatible with Obsidian and FixIt admonition shortcode.
   @param {String} .Text - The content of the admonition box
   @param {String} [.Type] - The type of the admonition box

layouts/_partials/plugin/pagefind-metadata.html

@@ -1,3 +1,11 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- if and .Site.Params.search.enable (eq .Site.Params.search.type "pagefind") .IsPage -}}
   {{- $pageDate := (.PublishDate | default .Date) -}}
   {{- $dateLabel := $pageDate | dateFormat (.Site.Params.date_format | default "2006-01-02") -}}

layouts/_partials/single/expiration-reminder.html

@@ -1,3 +1,11 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $expirationReminder := dict "Page" . "Key" "expiration_reminder" | partial "function/param.html" | default dict -}}
 
 {{- if $expirationReminder.enable | and (not .Params.password) -}}

layouts/_partials/single/post-author.html

@@ -1,3 +1,10 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $author := partial "function/get-author-map.html" .Params.author -}}
 {{- .Store.Set "author" $author -}}
 {{- $optim := slice 

layouts/_partials/single/post-included-in.html

@@ -1,3 +1,10 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $categories := slice -}}
 {{- range .GetTerms "categories" -}}
   {{- $categories = $categories | append (

layouts/_partials/single/reward.html

@@ -1,3 +1,10 @@
+{{- /*
+  Post reward/donation panel partial.
+
+  Reads the reward config from front matter and site defaults,
+  then delegates rendering to plugin/reward.html.
+*/ -}}
+
 {{- $reward := dict "Page" . "Key" "reward" | partial "function/param.html" -}}
 {{- $author := .Store.Get "author" -}}
 {{- $options := dict "Reward" $reward "Id" "fi-reward" "Author" $author.name -}}

layouts/_partials/store/script.html

@@ -1,3 +1,11 @@
+{{- /*
+  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.
+*/ -}}
+
 {{- $noop := .Page.WordCount -}}
 {{- $this := .Page.Store.Get "this" -}}
 {{- $script := $this.script | default slice -}}

layouts/_partials/store/style.html

@@ -1,3 +1,10 @@
+{{- /*
+  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.
+*/ -}}
 
 {{- $noop := .Page.WordCount -}}
 {{- $this := .Page.Store.Get "this" -}}