refactor(assets): improve custom script examples and SCSS configuration

- Add custom.js.example alongside custom.ts.example
- Update examples to use window.fixit instead of importing from theme source
- Add "Build" true for custom.ts in assets pipeline so esbuild compiles it
- Make code_font_family configurable via [params.appearance] in hugo.toml
- Standardize SCSS header comments: // → ///, remove Chinese text
- Add documented examples in custom.scss: fonts, page width, admonitions, task lists

assets/js/custom.js.example

@@ -0,0 +1,49 @@
+/**
+ * Custom JavaScript for FixIt site.
+ *
+ * Copy this file to your project's assets/js/ directory
+ * and rename it to custom.js to activate it.
+ * Access the FixIt public API via `window.fixit`.
+ * @see https://fixit.lruihao.cn
+ */
+
+const { fixit } = window
+
+class CustomScript {
+  constructor() {
+    this.init()
+  }
+
+  init() {
+    console.log('hello from custom.js!')
+    console.log('FixIt API:', fixit)
+
+    // Top-level properties
+    console.log('version:', fixit.version)
+    console.log('themeMode:', fixit.themeMode)
+    console.log('isDark:', fixit.isDark)
+    console.log('config:', fixit.config)
+
+    // Theme control
+    // fixit.setThemeMode('dark')
+    // fixit.setThemeMode('auto', true) // persist to localStorage
+
+    // Mask overlay (via core module)
+    // fixit.core.registerMaskOverlay('my-overlay', {
+    //   isActive: () => boolean,
+    //   onOpen: () => void,
+    //   onClose: () => void,
+    // })
+
+    // Typed event bus
+    fixit.eventBus.on('fixit:switch-theme', ({ detail }) => {
+      console.log('Theme switched:', detail.mode, 'isDark:', detail.isDark, 'isChanged:', detail.isChanged)
+    })
+
+    return this
+  }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  void new CustomScript()
+})

assets/js/custom.ts.example

@@ -1,14 +1,13 @@
 /**
  * Custom TypeScript for FixIt site.
  *
- * Rename this file to custom.ts to activate it.
- * Access the FixIt public API via `window.fixit` (type: FixItPublicAPI).
+ * Copy this file to your project's assets/js/ directory
+ * and rename it to custom.ts to activate it.
+ * Access the FixIt public API via `window.fixit`.
  * @see https://fixit.lruihao.cn
  */
 
-import type { FixItPublicAPI } from './types/ui'
-
-declare const fixit: FixItPublicAPI
+const { fixit } = window as any
 
 class CustomScript {
   constructor() {
@@ -17,11 +16,30 @@ class CustomScript {
 
   init() {
     console.log('hello from custom.ts!')
-    document.addEventListener('fixit:switch-theme', ({ detail }) => {
+    console.log('FixIt API:', fixit)
+
+    // Top-level properties
+    console.log('version:', fixit.version)
+    console.log('themeMode:', fixit.themeMode)
+    console.log('isDark:', fixit.isDark)
+    console.log('config:', fixit.config)
+
+    // Theme control
+    // fixit.setThemeMode('dark')
+    // fixit.setThemeMode('auto', true) // persist to localStorage
+
+    // Mask overlay (via core module)
+    // fixit.core.registerMaskOverlay('my-overlay', {
+    //   isActive: () => boolean,
+    //   onOpen: () => void,
+    //   onClose: () => void,
+    // })
+
+    // Typed event bus
+    fixit.eventBus.on('fixit:switch-theme', ({ detail }: { detail: { mode: string, isDark: boolean, isChanged: boolean } }) => {
       console.log('Theme switched:', detail.mode, 'isDark:', detail.isDark, 'isChanged:', detail.isChanged)
     })
-    console.log('FixIt API:', fixit)
-    console.log('FixIt config:', fixit.config)
+
     return this
   }
 }

assets/scss/_variables.scss

@@ -1,8 +1,9 @@
-// ==========================================================================
-// SCSS Variables
-// Configured via [params.appearance] in hugo.toml using hugo:vars.
-// Default values are defined in layouts/_partials/function/scss-vars.html.
-// ==========================================================================
+/// ==========================================================================
+/// SCSS Variables
+///
+/// Configured via [params.appearance] in hugo.toml using hugo:vars.
+/// Default values are defined in layouts/_partials/function/scss-vars.html.
+/// ==========================================================================
 @forward "core/maps";
 @use "sass:color";
 @use "hugo:vars" as v;
@@ -181,7 +182,7 @@ $code-font-size: v.$code-font-size;
 $code-block-font-size: v.$code-block-font-size;
 
 // Font family of the code
-$code-font-family: Source Code Pro, Menlo, Consolas, Monaco, monospace, $global-font-family !default;
+$code-font-family: v.$code-font-family, $global-font-family;
 // ========== Code ========== //
 
 // ========== GitHub Corners ========== //

assets/scss/core/_common.scss

@@ -1,7 +1,6 @@
-// ==============================
-// Common Styles
-// 常用样式
-// ==============================
+/// ==========================================================================
+/// Common Styles
+/// ==========================================================================
 @use "functions" as *;
 @use "mixins" as *;
 @use "maps" as maps;

assets/scss/core/_root.scss

@@ -1,19 +1,19 @@
-// ================================================================================
-// CSS Custom Properties (CSS Variables)
-// ================================================================================
-// This file defines all CSS custom properties for the FixIt theme.
-// Variables are organized into three main categories:
-// 1. Internal config: theme system values (base URL, logo, etc.) via hugo:vars/internal
-// 2. Theme-independent variables: fixed values (fonts, sizes, etc.)
-// 3. Theme-dependent variables: color values that support light/dark themes
-//
-// Theme-dependent variables are further categorized into:
-// - Core: Global layout and navigation colors
-// - Page Content: Article and post content colors
-// - Third-party: Extension and plugin colors
-//
-// These CSS variables enable runtime theme switching and customization.
-// ================================================================================
+/// ================================================================================
+/// CSS Custom Properties (CSS Variables)
+///
+/// This file defines all CSS custom properties for the FixIt theme.
+/// Variables are organized into three main categories:
+/// 1. Internal config: theme system values (base URL etc.) via hugo:vars/internal
+/// 2. Theme-independent variables: fixed values (fonts, sizes, etc.)
+/// 3. Theme-dependent variables: color values that support light/dark themes
+///
+/// Theme-dependent variables are further categorized into:
+/// - Core: Global layout and navigation colors
+/// - Page Content: Article and post content colors
+/// - Third-party: Extension and plugin colors
+///
+/// These CSS variables enable runtime theme switching and customization.
+/// ================================================================================
 @use "sass:color";
 @use "functions" as *;
 @use "mixins" as *;

assets/scss/core/mixins/_theme-vars.scss

@@ -1,6 +1,6 @@
-// ========================================
-// Theme Variable Mixins and Functions
-// ========================================
+/// ========================================
+/// Theme Variable Mixins and Functions
+/// ========================================
 @use "sass:color";
 @use "sass:map";
 @use "variables" as *;

assets/scss/custom.scss

@@ -1,4 +1,55 @@
-// ==============================
-// Custom style
-// 自定义样式
-// ==============================
+/// ==========================================================================
+/// Custom Styles
+///
+/// Copy this file to your project's assets/scss/ directory to activate it.
+/// See: https://fixit.lruihao.cn/documentation/advanced/#style-customization
+/// ==========================================================================
+// @use "core/mixins" as *;
+// ————————————————————————————————————————————————————————————
+// Custom Fonts
+// Configure font families via [params.appearance] in hugo.toml:
+//   global_font_family = "LXGW WenKai, system-ui, sans-serif"
+//   code_font_family = "Fira Mono, monospace"
+// Import custom font CSS below (skip if using system fonts).
+// ————————————————————————————————————————————————————————————
+// @import url('https://chinese-fonts-cdn.deno.dev/packages/lxgwwenkai/dist/LXGWWenKai-Regular/result.css');
+// @import url('https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext');
+
+// ————————————————————————————————————————————————————————————
+// Custom Page Width
+// Set pageStyle="custom" in the <body> element to apply.
+// ————————————————————————————————————————————————————————————
+// @include page-style('custom') {
+//   @include media('xl') {
+//     width: ROUND(70%, 2px);
+//     max-width: 1600px;
+//   }
+//   @include media('lg') {
+//     width: ROUND(60%, 2px);
+//   }
+//   @include media('md') {
+//     width: ROUND(56%, 2px);
+//   }
+// }
+
+// ————————————————————————————————————————————————————————————
+// Custom Admonitions
+// Add icon in hugo.toml first, e.g.:
+//   [params.admonition]
+//   ban = "fa-solid fa-ban"
+// Then use in content: {{</* admonition ban */>}} or > [!ban]
+// ————————————————————————————————————————————————————————————
+// .admonition {
+//   @include admonition(ban, #ff3d00, rgba(255, 61, 0, 0.1));
+// }
+
+// ————————————————————————————————————————————————————————————
+// Custom Task List Style
+// Add [params.taskList] in hugo.toml first, e.g.:
+//   [params.taskList]
+//   tip = "fa-regular fa-lightbulb"
+// ————————————————————————————————————————————————————————————
+// li[data-task='tip'] {
+//   @include task-icon(#EA9E36);
+//   @include task-text(#9974F7);
+// }

assets/scss/pages/single/code-syntax/_index.scss

@@ -1,12 +1,12 @@
-// ====================================================================================================
-// Code syntax highlighting for Chroma
-//
-// To generate syntax highlighting styles from the command line,
-// See https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles
-// For example:
-//   hugo gen chromastyles --style=github > assets/scss/pages/single/code-syntax/_light.scss
-//   hugo gen chromastyles --style=github-dark > assets/scss/pages/single/code-syntax/_dark.scss
-// ====================================================================================================
+/// ====================================================================================================
+/// Code syntax highlighting for Chroma
+///
+/// To generate syntax highlighting styles from the command line,
+/// See https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles
+/// For example:
+///   hugo gen chromastyles --style=github > assets/scss/pages/single/code-syntax/_light.scss
+///   hugo gen chromastyles --style=github-dark > assets/scss/pages/single/code-syntax/_dark.scss
+/// ====================================================================================================
 @use "sass:meta";
 @use "core/functions" as *;
 @use "core/mixins" as *;

layouts/_partials/base/assets.html

@@ -392,7 +392,7 @@
 
 {{- /* Custom script (custom.ts takes priority over custom.js) */ -}}
 {{- with resources.Get "js/custom.ts" | default (resources.Get "js/custom.js") -}}
-  {{- dict "Source" . "Fingerprint" $fingerprint "Defer" true | dict "Page" $ "Data" | partial "store/script.html" -}}
+  {{- dict "Source" . "Build" true "Fingerprint" $fingerprint "Defer" true | dict "Page" $ "Data" | partial "store/script.html" -}}
 {{- end -}}
 
 {{- with .Store.Get "styleArr" -}}

layouts/_partials/function/scss-vars.html

@@ -63,6 +63,7 @@
   "pagination_link_hover_color_dark" "#fff"
   "code_color" "#26323d"
   "code_color_dark" "#c5d1dc"
+  "code_font_family" "Source Code Pro, Menlo, Consolas, Monaco, monospace"
   "code_header_color" "#70808f"
   "code_header_color_dark" "#99a7b5"
   "code_header_background_color" "#dde6ef"

layouts/_partials/init/index.html

@@ -1,4 +1,4 @@
-{{- hugo.Store.Set "version" "v1.0.0-mq99hlzg" -}}
+{{- hugo.Store.Set "version" "v1.0.0-mqorjc8q" -}}
 {{- .Store.Set "this" dict -}}
 
 {{- partial "init/detection-env.html" . -}}