perf(home): disable third-party resource loading on the home page, and improve plugin comments

assets/js/lib/mermaid.js

@@ -1,7 +1,6 @@
 {{- /* Page level params is not supported */ -}}
 {{- $mermaid := .Site.Params.mermaid -}}
 {{- $mermaidCDN := $mermaid.cdn | default "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs" -}}
-{{- $wrapped := $mermaid.wrapper | default true -}}
 
 import mermaid from "{{ $mermaidCDN }}"
 {{- with $mermaid.zenuml }}
@@ -32,13 +31,12 @@ let mermaidContainerObserver = null
 let mermaidRenderLock = Promise.resolve()
 let mermaidConfigKey = ''
 let mermaidIdSeq = 0
-{{- if $wrapped }}
+// Panzoom states
 let panzoomInstances = null
 let panzoomWheelHosts = null
 let panzoomEventBound = false
 let mermaidThemeSyncBound = false
 let mermaidPanzoomGroups = null
-{{- end }}
 
 /**
  * Waits for the next animation frame.
@@ -48,7 +46,6 @@ function nextFrame() {
   return new Promise((resolve) => requestAnimationFrame(resolve))
 }
 
-{{- if $wrapped }}
 /**
  * Gets (and initializes) the panzoom shared state for a Mermaid diagram container.
  *
@@ -113,7 +110,6 @@ function applyPanzoomTransform(instance, transform) {
   instance.zoom(transform.scale, { animate: false, force: true })
   setTimeout(() => instance.pan(transform.x, transform.y, { animate: false, force: true }))
 }
-{{- end }}
 
 /**
  * Schedule task at idle time to avoid blocking critical rendering.
@@ -355,7 +351,6 @@ function observeMermaidContainers(root = document, refresh = false) {
   })
 }
 
-{{- if $wrapped }}
 /**
  * Gets the currently visible SVG for a diagram block that contains multiple Mermaid layers.
  * @param {Element} root
@@ -574,7 +569,6 @@ function bindRenderedPanzoom() {
     bindMermaidPanzoom(document.getElementById(svgId))
   })
 }
-{{- end }}
 
 /**
  * Binds a listener so Mermaid diagrams inside a tab panel render after tab switches.
@@ -593,7 +587,6 @@ function bindTabContainerChanged() {
   })
 }
 
-{{- if $wrapped }}
 /**
  * Binds theme switch synchronization for Panzoom transforms across Mermaid layers.
  * @returns {void}
@@ -664,7 +657,6 @@ function bindThemeSync() {
     })
   }
 }
-{{- end }}
 
 /**
  * Initializes Mermaid rendering, events, lazy loading and diagram controls.
@@ -678,11 +670,9 @@ async function init() {
     'color: #FF3670; font-weight: bold; font-size: 16px; text-shadow: 1px 1px 2px rgba(0,0,0,0.1);',
   )
 
-{{- if $wrapped }}
   initDiagramControls()
   bindRenderedPanzoom()
   bindThemeSync()
-{{- end }}
   bindTabContainerChanged()
 
   // Core: observe containers and render only when they become visible.

layouts/_markup/render-codeblock-echarts.html

@@ -3,9 +3,6 @@
   "Inner" .Inner
   "Resources" .Page.Resources
   "Position" .Position
+  "Page" .Page
   | partial "plugin/echarts.html"
 -}}
-{{- .Page.Store.Set "hasEcharts" true -}}
-{{- if eq hugo.Context.MarkupScope "home" -}}
-  {{- site.Home.Store.Set "hasEcharts" true -}}
-{{- end -}}

layouts/_markup/render-codeblock-json.html

@@ -1,5 +1,5 @@
 {{- $jsonViewer := .Attributes | merge .Page.Params.jsonViewer | merge .Page.Site.Params.jsonViewer -}}
-{{- if $jsonViewer.enable -}}
+{{- if $jsonViewer.enable | and (ne hugo.Context.MarkupScope "home") -}}
   {{- $attrs := printf `expand-depth="%v"` $jsonViewer.expanddepth -}}
   {{- $copyable := false -}}
   {{- with $jsonViewer.copyable -}}
@@ -13,9 +13,6 @@
   {{- end -}}
   <json-viewer value="{{ .Inner | jsonify }}" {{ $attrs | safeHTMLAttr }}{{ with $copyable}} copyable="{{ . | jsonify }}"{{ end }}></json-viewer>
   {{- .Page.Store.Set "hasJsonViewer" true -}}
-  {{- if eq hugo.Context.MarkupScope "home" -}}
-    {{- site.Home.Store.Set "hasJsonViewer" true -}}
-  {{- end -}}
 {{- else -}}
   {{- partial "plugin/code-block-wrapper.html" . -}}
 {{- end -}}

layouts/_markup/render-codeblock-mermaid.html

@@ -1,5 +1 @@
-{{- dict "Options" .Attributes "Inner" .Inner | partial "plugin/mermaid.html" -}}
-{{- .Page.Store.Set "hasMermaid" true -}}
-{{- if eq hugo.Context.MarkupScope "home" -}}
-  {{- site.Home.Store.Set "hasMermaid" true -}}
-{{- end -}}
+{{- dict "Options" .Attributes "Inner" .Inner "Page" .Page | partial "plugin/mermaid.html" -}}

layouts/_markup/render-passthrough.html

@@ -13,7 +13,7 @@
   Regular passthrough rendering:
     - [todo] support more features in future
 */ -}}
-{{- if $math.enable -}}
+{{- if $math.enable | and (ne hugo.Context.MarkupScope "home") -}}
   {{- if eq $math.type "katex" -}}
     {{- $katex := $math.katex -}}
     {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq $.Type "block") }}
@@ -29,9 +29,6 @@
       {{- else }}
         {{- .Value }}
         {{- $.Page.Store.Set "hasKaTeX" true -}}
-        {{- if eq hugo.Context.MarkupScope "home" -}}
-          {{- site.Home.Store.Set "hasKaTeX" true -}}
-        {{- end -}}
       {{- end }}
     {{- end -}}
   {{- else if eq $math.type "mathjax" -}}
@@ -41,9 +38,6 @@
       ${{ .Inner }}$
     {{- end -}}
     {{- $.Page.Store.Set "hasMathJax" true -}}
-    {{- if eq hugo.Context.MarkupScope "home" -}}
-      {{- site.Home.Store.Set "hasMathJax" true -}}
-    {{- end -}}
   {{- end -}}
 {{- else -}}
   {{- /* Regular passthrough rendering */ -}}

layouts/_partials/layouts/assets.html

@@ -348,7 +348,7 @@ FixIt theme assets partial
 
 {{- /* Mermaid plugin */ -}}
 {{- if .Store.Get "hasMermaid" | and (not $isArchivesOrOffline) -}}
-  {{- if .Site.Params.mermaid.wrapper -}}
+  {{- if .Store.Get "hasPanzoom" -}}
     {{- $source := $cdn.panzoomJS | default "lib/panzoom/panzoom.min.js" -}}
     {{- dict "Source" $source "Fingerprint" $fingerprint "Defer" true | dict "Page" $ "Data" | partial "store/script.html" -}}
   {{- end -}}

layouts/_partials/plugin/analytics.html

@@ -1,3 +1,11 @@
+{{- /*
+  Analytics script injector.
+  - Reads analytics config from Site Store.
+  - Conditionally renders provider snippets when enabled.
+  - Supported providers include Google, Fathom, Baidu, Umami, and others.
+  @param {Object} .Site Hugo site object
+*/ -}}
+
 {{- $analytics := .Site.Store.Get "analytics" | default dict -}}
 
 {{- if $analytics.enable -}}

layouts/_partials/plugin/code-block-wrapper.html

@@ -1,4 +1,14 @@
-{{- /* Hook for code blocks rendering */ -}}
+{{- /*
+  Code block wrapper hook for highlight output.
+  - Applies wrapper UI features based on codeblock config.
+  - Supports classic/modern modes, copy button, expand button, and line-number states.
+  @param {Object} .Attributes code block attributes
+  @param {Object} .Options code fence options
+  @param {String} .Inner raw code content
+  @param {Object} .Page current page context
+  @param {String} .Type language/type for current block
+*/ -}}
+
 {{- $config := .Attributes | merge .Page.Params.codeblock | merge .Page.Site.Params.codeblock -}}
 {{- $result := transform.HighlightCodeBlock . -}}
 {{- $wrapper := $result.Wrapped -}}

layouts/_partials/plugin/diagram-copy-btn.html

@@ -1,4 +1,8 @@
-{{- /* Diagram copy button */ -}}
+{{- /*
+  Copy button for diagram-like plugins.
+  @param {String} [.Label] aria label text for copy action
+*/ -}}
+
 {{- $label := .Label | default "Copy Diagram code" -}}
 
 <button type="button" class="diagram-copy-btn" aria-label="{{ $label }}">

layouts/_partials/plugin/echarts.html

@@ -1,4 +1,21 @@
-{{- /* ECharts support for code fences extended and shortcodes. */ -}}
+{{- /*
+  ECharts rendering partial for code fences extended syntax and shortcode usage.
+  - Skips rendering when MarkupScope is home.
+  - Supports chart options from inline content, data key, or resource file.
+  - Supports JavaScript template mode via js/file options.
+  @param {Object} [.Options] render options from shortcode or code fence attributes
+  @param {String} [.Options.width] chart container width (default: 100%)
+  @param {String} [.Options.height] chart container height (default: 30rem)
+  @param {Boolean} [.Options.js] whether to treat content as JS option builder
+  @param {Boolean} [.Options.async] whether JS template executes asynchronously
+  @param {String} [.Options.data] key of data source under data/echarts
+  @param {String} [.Options.file] local resource path for js/json/yaml/toml source
+  @param {String} [.Inner] inline chart option content
+  @param {Object} [.Page] current page context
+*/ -}}
+
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $width := .Options.width | default "100%" -}}
 {{- $height := .Options.height | default "30rem" -}}
 {{- $js := .Options.js | default false -}}
@@ -42,4 +59,7 @@
   <template>{{ $content | jsonify }}</template>
 {{- end -}}
 </div>
-{{- /* EOF */ -}}
+
+{{- .Page.Store.Set "hasEcharts" true -}}
+
+{{- end -}}

layouts/_partials/plugin/fixit-encryptor.html

@@ -1,3 +1,14 @@
+{{- /*
+  Encrypted content renderer.
+  - Encrypts content payload and renders decryptor UI.
+  - Supports full-page mode and partial mode with isolated target container.
+  @param {String} .Password encryption password
+  @param {String} .Content content to encrypt and render
+  @param {String} [.Message] custom input placeholder message
+  @param {Boolean} [.IsPartial] whether current render is partial mode
+  @param {Object} [.Page] current page context (required when IsPartial is true)
+*/ -}}
+
 {{- if .Password -}}
   {{- /* Content Encryption */ -}}
   {{- $content := dict "Content" .Content "Password" .Password | partial "function/content-encryption.html" -}}

layouts/_partials/plugin/icon.html

@@ -1,3 +1,14 @@
+{{- /*
+  Icon renderer for Font Awesome classes and SVG sources.
+  - Renders <i> element when Class is provided.
+  - Resolves local SVG resources or external SVG URL fallback.
+  - Supports Simple Icons shorthand by icon name.
+  @param {String} [.Class] icon class name for <i>
+  @param {String} [.Src] svg source path or URL
+  @param {String} [.Simpleicons] simple-icons icon name
+  @param {String} [.Prefix] custom prefix for simple-icons source path
+*/ -}}
+
 {{- with .Class -}}
   <i class="{{ . }}" aria-hidden="true"></i>
 {{- else -}}

layouts/_partials/plugin/mermaid.html

@@ -1,4 +1,17 @@
-{{- /* Mermaid support for code fences extended and shortcodes. */ -}}
+{{- /*
+  Mermaid rendering partial for code fences extended syntax and shortcode usage.
+  - Skips rendering when MarkupScope is home.
+  - Supports wrapped view with tabs/actions and plain diagram mode.
+  - Supports per-diagram filename for code/download actions.
+  @param {Object} [.Options] render options from shortcode or code fence attributes
+  @param {Boolean} [.Options.wrapper] whether to enable wrapped diagram UI
+  @param {String} [.Options.filename] filename used by diagram/code actions
+  @param {String} [.Inner] inline Mermaid source content
+  @param {Object} [.Page] current page context
+*/ -}}
+
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $code := strings.TrimSpace .Inner -}}
 {{- $wrapped := .Options.wrapper | default site.Params.mermaid.wrapper -}}
 
@@ -42,9 +55,10 @@
           <pre class="mermaid-neutral">{{ $code | safeHTML }}</pre>
         </div>
       </div>
-      {{- $codeFence | page.RenderString (dict "display" "block") -}}
+      {{- $codeFence | .Page.RenderString (dict "display" "block") -}}
     </div>
   </div>
+  {{- .Page.Store.Set "hasPanzoom" true -}}
 {{- else -}}
   <div class="diagram-container">
     <pre class="mermaid">{{ $code | safeHTML }}</pre>
@@ -54,3 +68,7 @@
     <template><pre>{{ $code | safeHTML }}</pre></template>
   </div>
 {{- end -}}
+
+{{- .Page.Store.Set "hasMermaid" true -}}
+
+{{- end -}}

layouts/_partials/plugin/reward.html

@@ -1,3 +1,12 @@
+{{- /*
+  Post reward panel renderer.
+  - Renders reward switch button and reward QR/payment images.
+  - Supports optional author prefix and animation mode.
+  @param {Object} .Reward reward config object
+  @param {String} .Id unique input id for reward toggle
+  @param {String} [.Author] optional author name for image alt text
+*/ -}}
+
 {{- $reward := .Reward -}}
 {{- $id := .Id -}}
 {{- $author := .Author | default "" -}}

layouts/_partials/plugin/script.html

@@ -1,3 +1,22 @@
+{{- /*
+  Script tag renderer.
+  - Accepts direct script HTML or builds script source from local/remote resources.
+  - Supports template execution, minify/build/fingerprint pipeline, and extra attrs.
+  @param {String} .Source script source URL/path or full <script> HTML
+  @param {String} [.Content] inline content to write as generated resource
+  @param {String} [.Path] resource path used with Content
+  @param {Object} [.Template] template name/path for ExecuteAsTemplate
+  @param {Object} [.Context] template context for ExecuteAsTemplate
+  @param {Boolean} [.Minify] whether to minify resource
+  @param {Object} [.Build] js.Build options
+  @param {String} [.Fingerprint] fingerprint algorithm
+  @param {Boolean} [.Async] whether to add async attribute
+  @param {Boolean} [.Defer] whether to add defer attribute
+  @param {Boolean} [.Crossorigin] whether to add crossorigin=anonymous
+  @param {String} [.Integrity] SRI hash value
+  @param {String} [.Attr] additional attributes
+*/ -}}
+
 {{- if strings.HasPrefix .Source "<script" -}}
   {{- safeHTML .Source -}}
 {{- else -}}

layouts/_partials/plugin/share.html

@@ -1,3 +1,10 @@
+{{- /*
+  Social share buttons renderer.
+  - Reads share switches from merged theme/page params.
+  - Outputs provider-specific sharer attributes for supported platforms.
+  @param {Object} .Page current page context
+*/ -}}
+
 {{- $share := (partial "function/params.html").share | default dict -}}
 
 {{- if $share.enable -}}

layouts/_partials/plugin/social.html

@@ -1,3 +1,13 @@
+{{- /*
+  Social profile link helper.
+  - Builds destination from explicit Url or from Prefix/Template/Id.
+  - Delegates final rendering to plugin/link.html with rel=me.
+  @param {String} [.Url] explicit target URL
+  @param {String} [.Template] URL template containing one %%v placeholder
+  @param {String} [.Prefix] URL prefix used to build Template
+  @param {String} [.Id] account id used by Template
+*/ -}}
+
 {{- $destination := "" -}}
 {{- with .Url -}}
   {{- $destination = . | relLangURL -}}

layouts/_partials/plugin/style.html

@@ -1,3 +1,21 @@
+{{- /*
+  Stylesheet tag renderer.
+  - Accepts direct <link> HTML or builds CSS resources from local paths/content.
+  - Supports template execution, optional toCSS, minify/fingerprint, and preload mode.
+  @param {String} .Source stylesheet URL/path or full <link> HTML
+  @param {String} [.Content] inline style content to write as generated resource
+  @param {String} [.Path] resource path used with Content
+  @param {Object} [.Template] template name/path for ExecuteAsTemplate
+  @param {Object} [.Context] template context for ExecuteAsTemplate
+  @param {Object} [.ToCSS] toCSS options
+  @param {Boolean} [.Minify] whether to minify resource
+  @param {String} [.Fingerprint] fingerprint algorithm
+  @param {Boolean} [.Crossorigin] whether to add crossorigin=anonymous
+  @param {Boolean} [.Preload] whether to output preload + noscript fallback
+  @param {String} [.Integrity] SRI hash value
+  @param {String} [.Attr] additional attributes
+*/ -}}
+
 {{- if strings.HasPrefix .Source "<link" -}}
   {{- safeHTML .Source -}}
 {{- else -}}

layouts/_partials/plugin/timeline.html

@@ -1,4 +1,20 @@
-{{- /* Timeline support for code fences extended and shortcodes. */ -}}
+{{- /*
+  Timeline rendering partial for code fences extended syntax and shortcode usage.
+  - Supports events from inline content, data key, resource file, or direct Events input.
+  - Supports reverse order, placement, animation, node style, and size options.
+  @param {Object} [.Options] render options from shortcode or code fence attributes
+  @param {Boolean} [.Options.reverse] whether to sort events in descending order
+  @param {String} [.Options.placement] default timestamp placement
+  @param {Boolean} [.Options.animation] whether to enable item animation
+  @param {String} [.Options.size] timeline size variant
+  @param {String} [.Options.node] timeline node style
+  @param {String} [.Options.data] key of data source under data/timeline
+  @param {String} [.Options.file] local resource path for timeline data
+  @param {String} [.Inner] inline timeline source content
+  @param {Array} [.Events] direct events array override
+  @param {Object} [.Page] current page context
+*/ -}}
+
 {{- $reverse := .Options.reverse | default false -}}
 {{- $placement := .Options.placement | default "bottom" -}}
 {{- $animation := .Options.animation | default false -}}

layouts/_shortcodes/aplayer.html

@@ -1,3 +1,5 @@
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- if .IsNamedParams -}}
   {{- $options := dict -}}
   {{- with .Get "fixed" -}}{{- $options = dict "fixed" . | merge $options -}}{{- end -}}
@@ -22,3 +24,5 @@
 {{- else -}}
   {{- errorf "Only named params is supported: %s" .Position -}}
 {{- end -}}
+
+{{- end -}}

layouts/_shortcodes/echarts.html

@@ -9,6 +9,6 @@
   "Inner" .Inner
   "Resources" .Page.Resources
   "Position" .Position
+  "Page" .Page
   | partial "plugin/echarts.html"
 -}}
-{{- .Page.Store.Set "hasEcharts" true -}}

layouts/_shortcodes/mapbox.html

@@ -1,3 +1,5 @@
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $mapbox := (.Page.Params | merge .Site.Params.page).mapbox | default dict -}}
 
 {{- $lng := cond .IsNamedParams (.Get "lng") (.Get 0) -}}
@@ -33,4 +35,7 @@
 
 {{- $attrs := printf `style="width: %v; height: %v;"` $width $height -}}
 <div class="mapbox" data-options="{{ $options | jsonify }}" {{ $attrs | safeHTMLAttr }}></div>
+
 {{- .Page.Store.Set "hasMapbox" true -}}
+
+{{- end -}}

layouts/_shortcodes/mermaid.html

@@ -2,5 +2,4 @@
   "wrapper" (.Get "wrapper")
   "filename" (.Get "filename")
 -}}
-{{- dict "Options" $options "Inner" .Inner | partial "plugin/mermaid.html" -}}
-{{- .Page.Store.Set "hasMermaid" true -}}
+{{- dict "Options" $options "Inner" .Inner "Page" .Page | partial "plugin/mermaid.html" -}}

layouts/_shortcodes/music.html

@@ -1,3 +1,5 @@
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $theme := "#448aff" -}}
 {{- if .IsNamedParams -}}
   {{- $theme = .Get "theme" | default $theme -}}
@@ -47,4 +49,7 @@
 {{- else -}}
   <meting-js server="{{ .Get 0 }}" type="{{ .Get 1 }}" id="{{ .Get 2 }}" theme="{{ $theme }}"></meting-js>
 {{- end -}}
+
 {{- .Page.Store.Set "hasMusic" true -}}
+
+{{- end -}}

layouts/_shortcodes/tabs.html

@@ -18,6 +18,9 @@
  
   Note: Tabs must be defined using the nested "tab" shortcode within the "tabs" shortcode.
 */ -}}
+
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $tabs := .Store.Get "tabs" -}}
 {{- if not $tabs -}}
   {{- errorf "No tabs found. Please add at least one tab to the tabs shortcode. See %s %s" .Name .Position -}}
@@ -45,7 +48,7 @@
   {{- end -}}
   {{- .Inner -}}
 </tab-container>
+
 {{- .Page.Store.Set "hasTabs" true -}}
-{{- if eq hugo.Context.MarkupScope "home" -}}
-  {{- site.Home.Store.Set "hasTabs" true -}}
+
 {{- end -}}

layouts/_shortcodes/typeit.html

@@ -1,4 +1,5 @@
-{{- /* trim the newline */ -}}
+{{- if ne hugo.Context.MarkupScope "home" -}}
+
 {{- $content := trim (partial "function/dos2unix.html" .Inner) "\n" -}}
 {{- $classList := slice -}}
 {{- with .Get "class" -}}
@@ -50,4 +51,7 @@
   {{- printf `<%v %v></%v>` $tag $innerAttrs $tag | safeHTML -}}
   <template><pre>{{ printf "%v" $content | safeHTML }}</pre></template>
 </div>
+
 {{- .Page.Store.Set "hasTyped" true -}}
+
+{{- end -}}