From 5322a15ceb4646c0622d4e9c8811004ccfc7fd6e Mon Sep 17 00:00:00 2001
From: Cell <1024@lruihao.cn>
Date: Thu, 23 Jul 2026 12:56:40 +0800
Subject: [PATCH] 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            |  9 +++++++++
 layouts/_partials/base/comment.html               | 10 ++++++++++
 layouts/_partials/base/footer.html                | 13 +++++++++++++
 layouts/_partials/base/head/index.html            |  1 -
 layouts/_partials/base/header.html                | 12 ++++++++++++
 layouts/_partials/base/paginator.html             |  7 +++++++
 layouts/_partials/base/widgets.html               | 15 +++++++++++++++
 layouts/_partials/custom.html                     |  9 +++++++++
 layouts/_partials/feed/rss.html                   |  8 ++++++++
 layouts/_partials/function/content.html           | 13 +++++++++++++
 layouts/_partials/function/get-remote-json.html   |  8 ++++++++
 layouts/_partials/function/is-cjk.html            |  6 ++++++
 layouts/_partials/function/is-url-remote.html     |  7 +++++++
 layouts/_partials/function/resource.html          | 11 +++++++++++
 layouts/_partials/function/xml-content.html       | 14 ++++++++++++++
 layouts/_partials/home/profile.html               |  9 +++++++++
 layouts/_partials/init/compatibility.html         |  7 +++++++
 layouts/_partials/init/detection-encryption.html  |  7 +++++++
 layouts/_partials/init/detection-pagefind.html    |  7 +++++++
 layouts/_partials/init/detection-version.html     |  8 ++++++++
 layouts/_partials/init/global.html                |  8 ++++++++
 layouts/_partials/init/index.html                 | 12 +++++++++++-
 layouts/_partials/plugin/admonition.html          |  3 ++-
 layouts/_partials/plugin/pagefind-metadata.html   |  8 ++++++++
 layouts/_partials/single/expiration-reminder.html |  8 ++++++++
 layouts/_partials/single/post-author.html         |  7 +++++++
 layouts/_partials/single/post-included-in.html    |  7 +++++++
 layouts/_partials/single/reward.html              |  7 +++++++
 layouts/_partials/store/script.html               |  8 ++++++++
 layouts/_partials/store/style.html                |  7 +++++++
 30 files changed, 253 insertions(+), 3 deletions(-)

diff --git a/layouts/_partials/base/breadcrumb.html b/layouts/_partials/base/breadcrumb.html
index d2249142..dcbbc6e1 100644
--- a/layouts/_partials/base/breadcrumb.html
+++ b/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 }}">
diff --git a/layouts/_partials/base/comment.html b/layouts/_partials/base/comment.html
index 71eed281..19715f1e 100644
--- a/layouts/_partials/base/comment.html
+++ b/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 -}}
diff --git a/layouts/_partials/base/footer.html b/layouts/_partials/base/footer.html
index 3fdb6165..ae14d32a 100644
--- a/layouts/_partials/base/footer.html
+++ b/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 -}}
diff --git a/layouts/_partials/base/head/index.html b/layouts/_partials/base/head/index.html
index 9774a4c1..ae724fa9 100644
--- a/layouts/_partials/base/head/index.html
+++ b/layouts/_partials/base/head/index.html
@@ -1,4 +1,3 @@
-
 {{- /*
   Head Partial - Comprehensive head section template
 
diff --git a/layouts/_partials/base/header.html b/layouts/_partials/base/header.html
index 5b29d91e..abb1f44b 100644
--- a/layouts/_partials/base/header.html
+++ b/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 "" -}}
 
diff --git a/layouts/_partials/base/paginator.html b/layouts/_partials/base/paginator.html
index 8733286f..f9f81b06 100644
--- a/layouts/_partials/base/paginator.html
+++ b/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 -}}
diff --git a/layouts/_partials/base/widgets.html b/layouts/_partials/base/widgets.html
index 50d71d03..044d05bb 100644
--- a/layouts/_partials/base/widgets.html
+++ b/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" -}}
diff --git a/layouts/_partials/custom.html b/layouts/_partials/custom.html
index b4637e19..aac08600 100644
--- a/layouts/_partials/custom.html
+++ b/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 -}}
diff --git a/layouts/_partials/feed/rss.html b/layouts/_partials/feed/rss.html
index 3d6effc8..dcf784a6 100644
--- a/layouts/_partials/feed/rss.html
+++ b/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 -}}
diff --git a/layouts/_partials/function/content.html b/layouts/_partials/function/content.html
index d927065b..94c53ae6 100644
--- a/layouts/_partials/function/content.html
+++ b/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 -}}
diff --git a/layouts/_partials/function/get-remote-json.html b/layouts/_partials/function/get-remote-json.html
index bd48270b..483f7ca2 100644
--- a/layouts/_partials/function/get-remote-json.html
+++ b/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 -}}
diff --git a/layouts/_partials/function/is-cjk.html b/layouts/_partials/function/is-cjk.html
index bbe082be..d26cdb47 100644
--- a/layouts/_partials/function/is-cjk.html
+++ b/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 -}}
 
diff --git a/layouts/_partials/function/is-url-remote.html b/layouts/_partials/function/is-url-remote.html
index 40217f74..85eb50a8 100644
--- a/layouts/_partials/function/is-url-remote.html
+++ b/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 -}}
diff --git a/layouts/_partials/function/resource.html b/layouts/_partials/function/resource.html
index c3dbf093..be27fe94 100644
--- a/layouts/_partials/function/resource.html
+++ b/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 -}}
diff --git a/layouts/_partials/function/xml-content.html b/layouts/_partials/function/xml-content.html
index c8d6f745..099faedd 100644
--- a/layouts/_partials/function/xml-content.html
+++ b/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 -}}
diff --git a/layouts/_partials/home/profile.html b/layouts/_partials/home/profile.html
index a3de2cb9..925995ef 100644
--- a/layouts/_partials/home/profile.html
+++ b/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 -}}
 
diff --git a/layouts/_partials/init/compatibility.html b/layouts/_partials/init/compatibility.html
index eb4ceb9c..da2d92b0 100644
--- a/layouts/_partials/init/compatibility.html
+++ b/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" -}}
diff --git a/layouts/_partials/init/detection-encryption.html b/layouts/_partials/init/detection-encryption.html
index 2efc55a7..56d87b4e 100644
--- a/layouts/_partials/init/detection-encryption.html
+++ b/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") -}}
diff --git a/layouts/_partials/init/detection-pagefind.html b/layouts/_partials/init/detection-pagefind.html
index 69a0ecb5..a9b4b3c6 100644
--- a/layouts/_partials/init/detection-pagefind.html
+++ b/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 -}}
diff --git a/layouts/_partials/init/detection-version.html b/layouts/_partials/init/detection-version.html
index 4bd79529..eed86ea1 100644
--- a/layouts/_partials/init/detection-version.html
+++ b/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" -}}
diff --git a/layouts/_partials/init/global.html b/layouts/_partials/init/global.html
index 8012b3d9..4249249e 100644
--- a/layouts/_partials/init/global.html
+++ b/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 */ -}}
diff --git a/layouts/_partials/init/index.html b/layouts/_partials/init/index.html
index 30786c19..946b6f68 100644
--- a/layouts/_partials/init/index.html
+++ b/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" . -}}
diff --git a/layouts/_partials/plugin/admonition.html b/layouts/_partials/plugin/admonition.html
index 9ed7c147..ddf5e092 100644
--- a/layouts/_partials/plugin/admonition.html
+++ b/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
diff --git a/layouts/_partials/plugin/pagefind-metadata.html b/layouts/_partials/plugin/pagefind-metadata.html
index dcf2b3e6..4e5232f0 100644
--- a/layouts/_partials/plugin/pagefind-metadata.html
+++ b/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") -}}
diff --git a/layouts/_partials/single/expiration-reminder.html b/layouts/_partials/single/expiration-reminder.html
index d53bbfbb..a347f84e 100644
--- a/layouts/_partials/single/expiration-reminder.html
+++ b/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) -}}
diff --git a/layouts/_partials/single/post-author.html b/layouts/_partials/single/post-author.html
index aa9b651a..93442763 100644
--- a/layouts/_partials/single/post-author.html
+++ b/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 
diff --git a/layouts/_partials/single/post-included-in.html b/layouts/_partials/single/post-included-in.html
index 23912e0e..1e56fad4 100644
--- a/layouts/_partials/single/post-included-in.html
+++ b/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 (
diff --git a/layouts/_partials/single/reward.html b/layouts/_partials/single/reward.html
index ca578362..abf069c3 100644
--- a/layouts/_partials/single/reward.html
+++ b/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 -}}
diff --git a/layouts/_partials/store/script.html b/layouts/_partials/store/script.html
index 7cbfa9e9..8d421936 100644
--- a/layouts/_partials/store/script.html
+++ b/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 -}}
diff --git a/layouts/_partials/store/style.html b/layouts/_partials/store/style.html
index b53273c8..209cc1c4 100644
--- a/layouts/_partials/store/style.html
+++ b/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" -}}