chore: update zh-cn translation

2025-08-23 18:07:14 -04:00 · 2025-08-14 19:07:25 +08:00
parent 8773081fae
commit f79b1d262c
29 changed files with 993 additions and 495 deletions
--- a/exampleSite/content/about/index.zh-cn.md
+++ b/exampleSite/content/about/index.zh-cn.md
@@ -3,15 +3,15 @@ title: 关于
 toc: false
 ---

-Hextra 是一款简洁、快速、灵活的主题，适用于构建现代化静态站点。Hextra 特别适用于文档网站，但也可用于构建博客、个人网站等各种类型的网站。
+Hextra 是一款专为构建现代化静态网站而设计的简洁、快速且灵活的主题。它尤其适合搭建文档类网站，同时也能轻松驾驭博客、作品集等多种站点类型。

-Hugo 和 Jekyll 类似，是一个静态网站生成器。但与其他生成器不同，Hugo 只有单个可执行文件，这使得它可以轻松地在各种平台上安装和运行。Hugo 的运行速度非常快且可靠性高，能够在几毫秒内渲染数千页的网站。
+与 Jekyll 类似，Hugo 同样是一款静态网站生成器。其独特之处在于采用单一二进制文件，可在多平台轻松安装运行。Hugo 以极致的速度与稳定性著称，能在毫秒间渲染包含数千页面的网站。

-Hextra 被设计为轻量级，具有最小化的内存占用。使用 Hextra 无需安装繁杂的依赖，比如 Node.js；相反，你只需要一个简单的 YAML 配置文件和 Markdown 内容。因此，我们可以专注于内容而非在配置环境上浪费精力。
+Hextra 秉持极简理念开发。您无需安装 Node.js 等额外依赖，仅需一个 YAML 配置文件搭配 Markdown 内容即可快速开始。这让我们能专注于创作优质内容，而非配置工具链。

-## 鸣谢
+## 致谢

-Hextra 的设计离不开这些项目的支持和其提供的灵感：
+Hextra 的诞生离不开以下工具与灵感的启发：

 - [Hugo](https://gohugo.io/)
 - [Tailwind CSS](https://tailwindcss.com/)
--- a/exampleSite/content/blog/markdown.zh-cn.md
+++ b/exampleSite/content/blog/markdown.zh-cn.md
@@ -2,8 +2,12 @@
 title: Markdown 语法指南
 date: 2020-01-01
 authors:
-  - name: John Doe
-    link: https://example.com/johndoe
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+  - name: Octocat
+    link: https://github.com/octocat
+    image: https://github.com/octocat.png
 tags:
  - Markdown
  - 示例
@@ -11,8 +15,7 @@ tags:
 excludeSearch: true
 ---

-这篇文章提供了一些基础的 Markdown 语法样例，这些可以在 Hugo 的内容文件中使用。
-
+本文展示了 Hugo 内容文件中可用的基础 Markdown 语法示例。
 <!--more-->

 ## 基础语法
@@ -34,40 +37,53 @@ excludeSearch: true
 ##### 五级标题
 ###### 六级标题

+### 强调
+
 ```text
-*这段文字将是斜体*
-_这也将是斜体_
+*这段文字会显示为斜体*
+_这段文字也会显示为斜体_

-**这段文字将是粗体**
-__这也将是粗体__
+**这段文字会显示为粗体**
+__这段文字也会显示为粗体__

-_你 **可以** 组合它们_
+_你可以**组合**使用_
 ```

-*这段文字将是斜体*
-_这也将是斜体_
+*这段文字会显示为斜体*

-**这段文字将是粗体**
-__这也将是粗体__
+_这段文字也会显示为斜体_

-_你 **可以** 组合它们_
+**这段文字会显示为粗体**
+
+__这段文字也会显示为粗体__
+
+_你可以**组合**使用_

 ### 列表

 #### 无序列表

-* 项目 1
-* 项目 2
-  * 项目 2a
-  * 项目 2b
+```
+* 项目1
+* 项目2
+  * 子项目2a
+  * 子项目2b
+```
+
+* 项目1
+* 项目2
+  * 子项目2a
+  * 子项目2b

 #### 有序列表

-1. 项目 1
-2. 项目 2
-3. 项目 3
-   1. 项目 3a
-   2. 项目 3b
+```
+1. 项目1
+2. 项目2
+3. 项目3
+   1. 子项目3a
+   2. 子项目3b
+```

 ### 图片

@@ -85,23 +101,23 @@ _你 **可以** 组合它们_

 [Hugo](https://gohugo.io)

-### 块引用
+### 引用块

 ```markdown
-牛顿曾说：
+正如牛顿所说：

-> 如果我看得更远，那是因为我站在巨人的肩膀上。
+> 如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。
 ```

-> 如果我看得更远，那是因为我站在巨人的肩膀上。
+> 如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。

 ### 行内代码

 ```markdown
-行内 `代码` 有 `反引号` 包围。
+行内`代码`会用`反引号包裹`起来。
 ```

-行内 `代码` 有 `反引号` 包围。
+行内`代码`会用`反引号包裹`起来。

 ### 代码块

@@ -124,18 +140,18 @@ func main() {
 ### 表格

 ```markdown
-| Syntax    | Description |
+| 语法      | 描述         |
 | --------- | ----------- |
-| Header    | Title       |
-| Paragraph | Text        |
+| 标题      | 标题文本     |
+| 段落      | 正文内容     |
 ```

-| Syntax    | Description |
+| 语法      | 描述         |
 | --------- | ----------- |
-| Header    | Title       |
-| Paragraph | Text        |
+| 标题      | 标题文本     |
+| 段落      | 正文内容     |

-## 参考
+## 参考资料

- [Markdown Syntax](https://www.markdownguide.org/basic-syntax/)
+- [Markdown 语法](https://www.markdownguide.org/basic-syntax/)
 - [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown)
--- a/exampleSite/content/blog/v0.10.md
+++ b/exampleSite/content/blog/v0.10.md
--- a/exampleSite/content/blog/v010.zh-cn.md
+++ b/exampleSite/content/blog/v010.zh-cn.md
@@ -0,0 +1,196 @@
+---
+title: "Hextra v0.10"
+date: 2025-08-14
+authors:
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+tags:
+  - Release
+draft: true
+---
+
+Hextra v0.10.0 是一个重大版本更新，包含了新功能、架构升级和体验优化。
+
+<!--more-->
+
+本次更新还包含了来自10位[新贡献者](#contributors)的贡献，并解决了社区长期以来的功能请求。
+
+## 升级指南
+
+> [!IMPORTANT]
+> **破坏性变更**：此版本包含多项破坏性变更。请在升级前查阅检查清单和[迁移指南](#migration-guide)。
+
+升级至 v0.10.0 前，请确保：
+- 已安装 Hugo v0.146.0+（扩展版）
+- 已检查自定义 CSS 的类名变更（参见[CSS 类前缀变更](#css-class-prefix-changes)和[Tailwind CSS v4](#tailwind-css-v4)）
+- 确认构建环境可访问互联网以下载 LaTeX 和/或 Mermaid 资源
+
+准备就绪后，更新 Hugo 模块：
+```bash
+hugo mod get -u github.com/imfing/hextra@v0.10.0
+```
+
+## 新功能
+
+以下是本版本值得关注的新功能：
+
+- [**导航栏下拉菜单支持**](#dropdown-menu-support-in-navbar)：创建层级导航菜单
+- [**增强搜索体验**](#enhanced-search-experience)：支持全标题搜索，准确率提升
+- [**llms.txt 支持**](#llmstxt-support)：生成 AI 友好的站点大纲
+- [**目录滚动高亮**](#table-of-contents-scroll-highlighting)：滚动页面时自动高亮当前章节
+- [**同步标签页切换**](#synchronized-tab-switching)：跨多个标签组同步选择状态
+- [**博客列表分页**](#blog-list-pagination)：为博客列表页添加分页控件
+- [**MathJax 支持**](#mathjax-support)：在 KaTeX 外新增数学公式渲染引擎
+
+### 导航栏下拉菜单支持
+
+通过层级结构组织导航项：
+```yaml {filename="hugo.yaml"}
+menu:
+  main:
+    - identifier: products
+      name: "产品"
+    - name: "产品A"
+      parent: products
+      url: "/product-a"
+    - name: "产品B"
+      parent: products
+      url: "/product-b"
+```
+
+![下拉菜单导航](https://github.com/user-attachments/assets/1816f9b9-7fe3-46e8-9546-f15e43e9914a)
+
+### 增强搜索体验
+
+- **全标题搜索**：支持所有层级标题的内容检索
+- **结果精准度提升**：优化标题处理和链接准确性
+- **修复结果导航**：搜索结果现在能正确跳转到对应章节
+
+特别感谢 [@ldez](https://github.com/ldez) 推动搜索功能改进！
+
+![增强版搜索结果](https://github.com/user-attachments/assets/f819652a-95d4-4843-b7e2-c7953a8cabe8)
+
+### llms.txt 支持
+
+现支持生成 [llms.txt](https://llmstxt.org/) 格式文件，便于 AI 工具理解站点内容：
+```yaml {filename="hugo.yaml"}
+outputs:
+  home: [html, llms]
+```
+
+![示例 llms 文件](https://github.com/user-attachments/assets/c6e929bb-0fce-4ab2-af15-a71c5a38b22c)
+
+### 目录滚动高亮
+
+滚动页面时自动高亮当前章节，导航更直观：
+![目录高亮效果](https://github.com/user-attachments/assets/d623fb99-7000-428b-af95-384eb722f0eb)
+
+### 同步标签页切换
+
+相同内容的标签组现在支持状态同步：
+```yaml {filename="hugo.yaml"}
+params:
+  page:
+    tabs:
+      sync: true
+```
+
+### 博客列表分页
+
+为博客列表添加基础分页控制：
+```yaml {filename="hugo.yaml"}
+params:
+  blog:
+    list:
+      pagerSize: 20 # 每页文章数
+```
+
+![博客分页效果](https://github.com/user-attachments/assets/60405fb4-ec36-4733-ba13-b4066396b5c5)
+
+### MathJax 支持
+
+新增 [MathJax](https://www.mathjax.org/) 作为数学公式渲染引擎：
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: "mathjax" # 默认为 "katex"
+```
+
+## 技术改进
+
+### 框架与构建系统
+
+- **Tailwind CSS v4 迁移**：全面升级至 [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4)
+- **Hugo 模板系统**：适配 Hugo [新模板系统](https://gohugo.io/templates/new-templatesystem-overview/)
+- **数学公式服务端渲染**：默认使用 Hugo 原生渲染
+- **FlexSearch 0.8 升级**：优化 CJK（中日韩）内容编码处理
+- **资源管理增强**：支持从 CDN 或本地加载 KaTeX 和 Mermaid 资源
+
+## 体验优化
+
+- **动态 favicon 切换**：随主题色自动更新
+- **反向分页**：通过 front matter 设置 `reversePagination`
+- **Google 索引控制**：新增页面参数控制索引
+- **宽度处理优化**：通过 CSS 变量改进响应式设计
+- **样式改进**：现代化 Markdown 表格和水平线样式
+
+## 问题修复
+
+- **Giscus 主题同步**：评论框现正确跟随暗/亮模式切换
+- **搜索结果准确性**：修复链接和标题转义问题
+- **标签页切换**：解决非同步模式下的导航问题
+- **幽灵滚动**：修复禁用页脚时的异常滚动
+- **图片可访问性**：避免重复渲染 alt 文本
+- **链接渲染**：改进复杂站点结构的 base URL 处理
+
+---
+
+## 迁移指南
+
+- [**Hugo 版本要求**](#hugo-version-requirements)：需 Hugo v0.146.0+（扩展版）
+- [**CSS 类前缀变更**](#css-class-prefix-changes)：组件类名统一添加 `hextra-` 前缀
+- [**资源管理**](#asset-management-for-katex-and-mermaid)：KaTeX 和 Mermaid 资源改为构建时下载
+- [**Tailwind CSS v4**](#tailwind-css-v4)：内部 CSS 编译使用 Tailwind CSS v4.x 带 `hx:` 前缀
+
+#### Hugo 版本要求
+
+**影响**：使用旧版 Hugo 的站点
+
+**解决方案**：升级至 Hugo v0.146.0+
+
+#### CSS 类前缀变更
+
+**影响**：自定义 CSS 针对 Hextra 组件的站点
+
+**变更对照表**：
+
+| 区域                | 旧类名                 | 新类名                          |
+|--------------------|-----------------------|--------------------------------|
+| 搜索容器           | `.search-wrapper`     | `.hextra-search-wrapper`       |
+| 导航栏模糊效果     | `.nav-container-blur` | `.hextra-nav-container-blur`   |
+| 侧边栏激活项       | `.sidebar-active-item`| `.hextra-sidebar-active-item`  |
+| 代码文件名         | `.filename`           | `.hextra-code-filename`        |
+
+#### KaTeX 和 Mermaid 资源管理
+
+**影响**：使用数学公式或流程图的站点
+
+**注意事项**：
+- 构建环境需联网下载资源
+- 隔离环境需预下载资源并配置加载路径
+
+#### Tailwind CSS v4
+
+**变更点**：
+- 工具类前缀从 `hx-` 改为 `hx:`
+- 内部样式表全面升级
+
+## 贡献者
+
+感谢10位新贡献者：
+- [@oosquare](https://github.com/oosquare) - KaTeX 字体优化
+- [@ldez](https://github.com/ldez) - 搜索功能改进
+- ...（其他贡献者列表保持原格式）
+
+**完整更新日志**：https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0
--- a/exampleSite/content/docs/_index.zh-cn.md
+++ b/exampleSite/content/docs/_index.zh-cn.md
@@ -1,38 +1,38 @@
 ---
 linkTitle: "文档"
-title: 介绍
+title: 简介
 ---

-👋 你好！欢迎来到 Hextra 文档！
+👋 你好！欢迎来到 Hextra 文档中心！

 <!--more-->

 ## 什么是 Hextra？

-Hextra 是一个现代、快速且功能齐全的 [Hugo][hugo] 主题，基于 [Tailwind CSS][tailwind-css] 构建。专为构建美观的文档、博客和网站而设计，它提供了开箱即用的功能和灵活性，以满足各种需求。
+Hextra 是一个基于 [Tailwind CSS][tailwind-css] 构建的现代化、高性能且开箱即用的 [Hugo][hugo] 主题。专为打造文档、博客和网站而设计，它提供丰富的内置功能和灵活配置，满足多样化需求。

-## 特性
+## 核心特性

- **精美设计** - 灵感源自 Nextra，Hextra 利用 Tailwind CSS 提供现代设计，使您的网站脱颖而出。
- **响应式布局与暗黑模式** - 在所有设备上都能完美呈现，从手机、平板到桌面。暗黑模式也得到支持，以适应不同的光照条件。
- **快速且轻量** - 由 Hugo 驱动，这是一个闪电般快速的静态网站生成器，仅需一个二进制文件，Hextra 保持其占用空间最小。无需 JavaScript 或 Node.js 即可使用。
- **全文搜索** - 内置离线全文搜索，由 FlexSearch 提供支持，无需额外配置。
- **功能齐全** - Markdown、语法高亮、LaTeX 数学公式、图表和 Shortcodes 元素，丰富您的内容。目录、面包屑导航、分页、侧边栏导航等均自动生成。
- **多语言与 SEO 就绪** - 通过 Hugo 的多语言模式轻松创建多语言网站。开箱即用支持 SEO 标签、Open Graph 和 Twitter Cards。
+- **精美设计** - 灵感源自 Nextra，采用 Tailwind CSS 实现现代美学，让您的站点脱颖而出。
+- **响应式布局与暗黑模式** - 完美适配移动设备、平板及桌面端，并支持根据环境光线自动切换的暗黑模式。
+- **极速轻量** - 依托 Hugo 静态网站生成器的单文件二进制架构，无需 JavaScript 或 Node.js 环境即可运行。
+- **全文搜索** - 内置基于 FlexSearch 的离线全文搜索功能，零配置开箱即用。
+- **功能完备** - 支持 Markdown 语法高亮、LaTeX 数学公式、图表和 Shortcodes 等丰富内容元素。自动生成目录导航、面包屑、分页及侧边栏等组件。
+- **多语言与 SEO 友好** - 通过 Hugo 多语言模式轻松构建国际化站点，原生集成 SEO 标签、Open Graph 和 Twitter Cards 支持。

-## 有问题或反馈？
+## 问题或建议？

 {{< callout emoji="❓" >}}
  Hextra 仍在积极开发中。
-  有问题或反馈？欢迎[提交问题](https://github.com/imfing/hextra/issues)！
+  如有疑问或反馈，欢迎[提交 Issue](https://github.com/imfing/hextra/issues)！
 {{< /callout >}}

 ## 下一步

-立即深入以下部分，开始使用：
+立即开始探索：

 {{< cards >}}
-  {{< card link="getting-started" title="入门指南" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
+  {{< card link="getting-started" title="快速开始" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
 {{< /cards >}}

 [hugo]: https://gohugo.io/
--- a/exampleSite/content/docs/advanced/_index.zh-cn.md
+++ b/exampleSite/content/docs/advanced/_index.zh-cn.md
@@ -5,12 +5,12 @@ prev: /docs/guide/shortcodes/tabs
 next: /docs/advanced/multi-language
 ---

-本节涵盖了一些主题的高级内容。
+本节涵盖该主题的一些高级内容。

 <!--more-->

 {{< cards >}}
-  {{< card link="multi-language" title="多语言" icon="translate" >}}
-  {{< card link="customization" title="自定义" icon="pencil" >}}
+  {{< card link="multi-language" title="多语言支持" icon="translate" >}}
+  {{< card link="customization" title="自定义配置" icon="pencil" >}}
  {{< card link="comments" title="评论系统" icon="chat-alt" >}}
 {{< /cards >}}
--- a/exampleSite/content/docs/advanced/comments.zh-cn.md
+++ b/exampleSite/content/docs/advanced/comments.zh-cn.md
@@ -10,7 +10,7 @@ Hextra 支持为您的网站添加评论系统。

 ## giscus

-[giscus](https://giscus.app/) 是一个由 [GitHub Discussions](https://docs.github.com/en/discussions) 提供支持的评论系统。它是免费且开源的。
+[giscus](https://giscus.app/) 是一个由 [GitHub Discussions](https://docs.github.com/en/discussions) 驱动的评论系统。它是免费且开源的。

 要启用 giscus，您需要在网站配置文件中添加以下内容：

@@ -27,7 +27,7 @@ params:
      categoryId: <分类 ID>
 ```

-giscus 的配置可以从 [giscus.app](https://giscus.app/) 网站生成。更多详细信息也可以在那里找到。
+giscus 的配置可以从 [giscus.app](https://giscus.app/) 网站生成。更多详情也可以在那里找到。

 可以在页面的 front matter 中为特定页面启用或禁用评论：

--- a/exampleSite/content/docs/advanced/customization.zh-cn.md
+++ b/exampleSite/content/docs/advanced/customization.zh-cn.md
@@ -3,18 +3,18 @@ title: 自定义 Hextra
 linkTitle: 自定义
 ---

-Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，用于配置主题。
-本页描述了可用的选项以及如何进一步自定义主题。
+Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项来配置主题。
+本页描述了可用选项以及如何进一步自定义主题。

 <!--more-->

 ## 自定义 CSS

-要添加自定义 CSS，我们需要在站点中创建一个文件 `assets/css/custom.css`。Hextra 会自动加载此文件。
+要添加自定义 CSS，我们需要在站点中创建 `assets/css/custom.css` 文件。Hextra 会自动加载此文件。

-### 字体
+### 字体家族

-内容的字体可以通过以下方式自定义：
+可以使用以下方式自定义内容的字体家族：

 ```css {filename="assets/css/custom.css"}
 .content {
@@ -22,9 +22,9 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，
 }
 ```

-### 内联代码元素
+### 行内代码元素

-与 `其他文本` 混合的文本颜色可以通过以下方式自定义：
+与 `其他文本` 混合的代码文本颜色可以通过以下方式自定义：

 ```css {filename="assets/css/custom.css"}
 .content code:not(.code-block code) {
@@ -34,7 +34,7 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 ### 主色调

-主题的主色调可以通过设置 `--primary-hue`、`--primary-saturation` 和 `--primary-lightness` 变量来自定义：
+可以通过设置 `--primary-hue`、`--primary-saturation` 和 `--primary-lightness` 变量来自定义主题的主色调：

 ```css {filename="assets/css/custom.css"}
 :root {
@@ -44,9 +44,42 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，
 }
 ```

-### 进一步的主题自定义
+### 组件布局变量

-可以通过覆盖暴露的 CSS 类来进一步自定义主题。以下是一个自定义页脚元素的示例：
+Hextra 提供了 CSS 变量来自定义页面、导航栏和页脚的宽度：
+
+```css {filename="assets/css/custom.css"}
+:root {
+  /* 页面宽度 - 也可以通过 hugo.yaml 中的 params.page.width 配置 */
+  --hextra-max-page-width: 80rem; /* 默认值：80rem（普通），90rem（宽版），100%（全宽） */
+
+  /* 导航栏宽度 - 也可以通过 hugo.yaml 中的 params.navbar.width 配置 */
+  --hextra-max-navbar-width: 90rem; /* 独立的导航栏宽度 */
+
+  /* 页脚宽度 - 也可以通过 hugo.yaml 中的 params.footer.width 配置 */
+  --hextra-max-footer-width: 80rem; /* 独立的页脚宽度 */
+}
+```
+
+### Tailwind 主题变量
+
+从基于 Tailwind CSS v4 的 Hextra v0.10.0 开始，您可以通过在 `@layer theme` 块中覆盖 CSS 变量来自定义主题。
+
+这样可以在不修改每个单独类的情况下自定义全局外观。
+
+```css {filename="assets/css/custom.css"}
+@layer theme {
+  :root {
+    --hx-default-mono-font-family: "JetBrains Mono", monospace;
+  }
+}
+```
+
+详情请参阅 [Tailwind 主题变量文档](https://tailwindcss.com/docs/theme#default-theme-variable-reference)。
+
+### 进一步主题自定义
+
+可以通过覆盖暴露的 CSS 类来自定义主题的默认样式。以下是一个自定义页脚元素的示例：

 ```css {filename="assets/css/custom.css"}
 .hextra-footer {
@@ -54,7 +87,7 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，
 }

 .hextra-footer:is(html[class~="dark"] *) {
-  /* 样式将应用于暗模式下的页脚元素 */
+  /* 样式将应用于暗黑模式下的页脚元素 */
 }
 ```

@@ -82,11 +115,11 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 - `hextra-cards` - 卡片网格容器

-##### Jupyter Notebook
+##### Jupyter 笔记本

- `hextra-jupyter-code-cell` - Jupyter 代码单元容器
- `hextra-jupyter-code-cell-outputs-container` - Jupyter 代码单元输出容器
- `hextra-jupyter-code-cell-outputs` - Jupyter 代码单元输出 div 元素
+- `hextra-jupyter-code-cell` - Jupyter 代码单元格容器
+- `hextra-jupyter-code-cell-outputs-container` - Jupyter 代码单元格输出容器
+- `hextra-jupyter-code-cell-outputs` - Jupyter 代码单元格输出 div 元素

 ##### PDF

@@ -94,7 +127,7 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 ##### 步骤

- `steps` - 步骤容器
+- `hextra-steps` - 步骤容器

 ##### 标签页

@@ -111,9 +144,9 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 #### 导航栏

- `nav-container` - 导航栏容器
- `nav-container-blur` - 导航栏模糊元素
- `hamburger-menu` - 汉堡菜单按钮
+- `hextra-nav-container` - 导航栏容器
+- `hextra-nav-container-blur` - 导航栏模糊效果容器
+- `hextra-hamburger-menu` - 汉堡菜单按钮

 #### 页脚

@@ -122,9 +155,18 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 #### 搜索

- `search-wrapper` - 搜索包装容器
- `search-input` - 搜索输入元素
- `search-results` - 搜索结果列表容器
+- `hextra-search-wrapper` - 搜索包装容器
+- `hextra-search-input` - 搜索输入元素
+- `hextra-search-results` - 搜索结果列表容器
+
+搜索 UI 中使用的可选嵌套类：
+
+- `hextra-search-title` - 结果标题元素
+- `hextra-search-active` - 活动结果锚点
+- `hextra-search-no-result` - 空状态元素
+- `hextra-search-prefix` - 分组结果的面包屑/前缀标签
+- `hextra-search-excerpt` - 结果片段文本
+- `hextra-search-match` - 高亮查询范围

 #### 目录

@@ -132,27 +174,29 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 #### 侧边栏

- `mobile-menu-overlay` - 移动菜单的覆盖元素
- `sidebar-container` - 侧边栏容器
- `sidebar-active-item` - 侧边栏中的活动项
+- `hextra-sidebar-container` - 侧边栏容器
+- `hextra-sidebar-active-item` - 侧边栏中的活动项

 #### 语言切换器

- `language-switcher` - 语言切换按钮
- `language-options` - 语言选项容器
+- `hextra-language-switcher` - 语言切换按钮
+- `hextra-language-options` - 语言选项容器

 #### 主题切换

- `theme-toggle` - 主题切换按钮
+- `hextra-theme-toggle` - 主题切换按钮

 #### 代码复制按钮

 - `hextra-code-copy-btn-container` - 代码复制按钮容器
 - `hextra-code-copy-btn` - 代码复制按钮
+- `hextra-copy-icon` - 复制图标元素
+- `hextra-success-icon` - 成功图标元素

 #### 代码块

 - `hextra-code-block` - 代码块容器
+- `hextra-code-filename` - 代码块的文件名元素

 #### 功能卡片

@@ -162,10 +206,6 @@ Hextra 在 `hugo.yaml` 配置文件中提供了一些默认的自定义选项，

 - `hextra-feature-grid` - 功能网格容器

-#### 面包屑导航
-
-面包屑导航没有特定的类。
-
 ### 语法高亮

 可用的语法高亮主题列表可在 [Chroma 样式库](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表：
@@ -178,7 +218,7 @@ hugo gen chromastyles --style=github

 ## 自定义脚本

-你可以通过添加以下文件在每个页面的 head 末尾添加自定义脚本：
+您可以通过添加以下文件在每个页面的 head 末尾添加自定义脚本：

 ```
 layouts/partials/custom/head-end.html
@@ -186,26 +226,26 @@ layouts/partials/custom/head-end.html

 ## 自定义页脚额外部分

-你可以通过在站点中创建文件 `layouts/partials/custom/footer.html` 来在页脚中添加额外部分。
+您可以通过在站点中创建 `layouts/partials/custom/footer.html` 文件来添加页脚的额外部分。

 ```html {filename="layouts/partials/custom/footer.html"}
-<!-- 你的页脚元素在这里 -->
+<!-- 您的页脚元素放在这里 -->
 ```

 添加的部分将出现在页脚的版权部分之前。
-你可以使用 [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) 和 [Hugo 模板语法](https://gohugo.io/templates/) 来添加自己的内容。
+您可以使用 [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) 和 [Hugo 模板语法](https://gohugo.io/templates/) 添加自己的内容。

-页脚部分可用的 Hugo 变量有：`.switchesVisible` 和 `.copyrightVisible`。
+页脚部分可用的 Hugo 变量有：`.switchesVisible` 和 `.displayCopyright`。

 ## 自定义布局

 可以通过在站点的 `layouts` 目录中创建同名文件来覆盖主题的布局。
-例如，要覆盖文档的 `single.html` 布局，可以在站点中创建文件 `layouts/docs/single.html`。
+例如，要覆盖文档的 `single.html` 布局，可以在站点中创建 `layouts/docs/single.html` 文件。

 更多信息，请参阅 [Hugo 模板文档][hugo-template-docs]。

 ## 进一步自定义

-没有找到你想要的？欢迎 [发起讨论](https://github.com/imfing/hextra/discussions) 或为主题做出贡献！
+没有找到您需要的内容？欢迎 [发起讨论](https://github.com/imfing/hextra/discussions) 或为主题做出贡献！

 [hugo-template-docs]: https://gohugo.io/templates/
--- a/exampleSite/content/docs/advanced/multi-language.zh-cn.md
+++ b/exampleSite/content/docs/advanced/multi-language.zh-cn.md
@@ -8,9 +8,9 @@ Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-manageme

 <!--more-->

-## 启用多语言
+## 启用多语言功能

-要使我们的网站支持多语言，我们需要告诉 Hugo 支持的语言。我们需要在站点配置文件中添加：
+要使网站支持多语言，我们需要在站点配置文件中指定支持的语言：

 ```yaml {filename="hugo.yaml"}
 defaultContentLanguage: en
@@ -28,7 +28,7 @@ languages:

 ## 通过文件名管理翻译

-Hugo 支持通过文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，我们可以创建一个文件 `content/docs/_index.fr.md` 作为法语翻译。
+Hugo 支持通过文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，可以创建 `content/docs/_index.fr.md` 作为法语翻译。

 {{< filetree/container >}}
  {{< filetree/folder name="content" >}}
@@ -40,11 +40,11 @@ Hugo 支持通过文件名管理翻译。例如，如果我们有一个英文文
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-注意：Hugo 还支持[通过内容目录进行翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。
+注意：Hugo 还支持[通过内容目录翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。

 ## 翻译菜单项

-要翻译导航栏中的菜单项，我们需要设置 `identifier` 字段：
+要翻译导航栏中的菜单项，需要设置 `identifier` 字段：

 ```yaml {filename="hugo.yaml"}
 menu:
@@ -59,7 +59,7 @@ menu:
      weight: 2
 ```

-并在相应的 i18n 文件中进行翻译：
+并在对应的 i18n 文件中进行翻译：

 ```yaml {filename="i18n/fr.yaml"}
 documentation: Documentation
@@ -68,7 +68,7 @@ blog: Blog

 ## 翻译字符串

-要翻译其他地方的字符串，我们需要将翻译添加到相应的 i18n 文件中：
+要翻译其他位置的字符串，需要将翻译添加到对应的 i18n 文件中：

 ```yaml {filename="i18n/fr.yaml"}
 readMore: Lire la suite
@@ -76,7 +76,7 @@ readMore: Lire la suite

 主题中使用的字符串列表可以在 `i18n/en.yaml` 文件中找到。

-## 了解更多
+## 延伸阅读

 - [Hugo 多语言模式](https://gohugo.io/content-management/multilingual/)
 - [Hugo 多语言第一部分：内容翻译](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
--- a/exampleSite/content/docs/getting-started.zh-cn.md
+++ b/exampleSite/content/docs/getting-started.zh-cn.md
@@ -1,5 +1,5 @@
 ---
-title: 入门指南
+title: 快速开始
 weight: 1
 tags:
  - 文档
@@ -8,28 +8,28 @@ next: /docs/guide
 prev: /docs
 ---

-## 从模板快速开始
+## 从模板快速启动

 {{< icon "github" >}}&nbsp;[imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)

-您可以通过使用上述模板仓库快速入门。
+您可以通过使用上述模板仓库快速开始。

 <img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">

-我们提供了一个 [GitHub Actions 工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，可以帮助自动构建并将您的站点部署到 GitHub Pages，并免费托管。
-更多选项，请查看 [部署站点](../guide/deploy-site)。
+我们提供了一个[GitHub Actions工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，可以帮助自动构建并将您的站点部署到GitHub Pages，并免费托管。
+更多选项，请查看[部署站点](../guide/deploy-site)。

 [🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/)

-## 作为新项目开始
+## 作为新项目启动

-有两种主要方式将 Hextra 主题添加到您的 Hugo 项目中：
+有两种主要方式将Hextra主题添加到您的Hugo项目中：

-1. **Hugo 模块（推荐）**：最简单且推荐的方法。[Hugo 模块](https://gohugo.io/hugo-modules/)允许您直接从在线源拉取主题。主题会自动下载并由 Hugo 管理。
+1. **Hugo模块（推荐）**：最简单且推荐的方法。[Hugo模块](https://gohugo.io/hugo-modules/)允许您直接从在线源拉取主题。主题会自动下载并由Hugo管理。

-2. **Git 子模块**：或者，将 Hextra 添加为 [Git 子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。主题由 Git 下载并存储在您项目的 `themes` 文件夹中。
+2. **Git子模块**：或者，将Hextra添加为[Git子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。主题由Git下载并存储在项目的`themes`文件夹中。

-### 将 Hextra 设置为 Hugo 模块
+### 将Hextra设置为Hugo模块

 #### 先决条件

@@ -43,24 +43,24 @@ prev: /docs

 {{% steps %}}

-### 初始化一个新的 Hugo 站点
+### 初始化一个新的Hugo站点

 ```shell
 hugo new site my-site --format=yaml
 ```

-### 通过模块配置 Hextra 主题
+### 通过模块配置Hextra主题

 ```shell
-# 初始化 Hugo 模块
+# 初始化Hugo模块
 cd my-site
 hugo mod init github.com/username/my-site

-# 添加 Hextra 主题
+# 添加Hextra主题
 hugo mod get github.com/imfing/hextra
 ```

-配置 `hugo.yaml` 以使用 Hextra 主题，添加以下内容：
+配置`hugo.yaml`以使用Hextra主题，添加以下内容：

 ```yaml
 module:
@@ -70,7 +70,7 @@ module:

 ### 创建您的内容页面

-为主页和文档页面创建新的内容页面：
+为主页和文档页面创建新内容：

 ```shell
 hugo new content/_index.md
@@ -83,30 +83,30 @@ hugo new content/docs/_index.md
 hugo server --buildDrafts --disableFastRender
 ```

-恭喜，您的新站点预览可在 `http://localhost:1313/` 查看。
+恭喜，您的新站点预览可在`http://localhost:1313/`查看。

 {{% /steps %}}


 {{% details title="如何更新主题？" %}}

-要更新项目中所有 Hugo 模块到最新版本，请运行以下命令：
+要更新项目中的所有Hugo模块到最新版本，运行以下命令：

 ```shell
 hugo mod get -u
 ```

-要将 Hextra 更新到 [最新发布版本](https://github.com/imfing/hextra/releases)，请运行以下命令：
+要将Hextra更新到[最新发布版本](https://github.com/imfing/hextra/releases)，运行以下命令：

 ```shell
 hugo mod get -u github.com/imfing/hextra
 ```

-有关更多详细信息，请参阅 [Hugo 模块](https://gohugo.io/hugo-modules/use-modules/#update-all-modules)。
+更多详情请参阅[Hugo模块](https://gohugo.io/hugo-modules/use-modules/#update-all-modules)。

 {{% /details %}}

-### 将 Hextra 设置为 Git 子模块
+### 将Hextra设置为Git子模块

 #### 先决条件

@@ -119,28 +119,28 @@ hugo mod get -u github.com/imfing/hextra

 {{% steps %}}

-### 初始化一个新的 Hugo 站点
+### 初始化一个新的Hugo站点

 ```shell
 hugo new site my-site --format=yaml
 ```

-### 将 Hextra 主题添加为 Git 子模块
+### 将Hextra主题添加为Git子模块

-切换到站点目录并初始化新的 Git 仓库：
+切换到站点目录并初始化一个新的Git仓库：

 ```shell
 cd my-site
 git init
 ```

-然后，将 Hextra 主题添加为 Git 子模块：
+然后，将Hextra主题添加为Git子模块：

 ```shell
 git submodule add https://github.com/imfing/hextra.git themes/hextra
 ```

-配置 `hugo.yaml` 以使用 Hextra 主题，添加以下内容：
+配置`hugo.yaml`以使用Hextra主题，添加以下内容：

 ```yaml
 theme: hextra
@@ -148,7 +148,7 @@ theme: hextra

 ### 创建您的内容页面

-为主页和文档页面创建新的内容页面：
+为主页和文档页面创建新内容：

 ```shell
 hugo new content/_index.md
@@ -161,35 +161,35 @@ hugo new content/docs/_index.md
 hugo server --buildDrafts --disableFastRender
 ```

-您的新站点预览可在 `http://localhost:1313/` 查看。
+您的新站点预览可在`http://localhost:1313/`查看。

 {{% /steps %}}


-当使用 [CI/CD](https://en.wikipedia.org/wiki/CI/CD) 部署 Hugo 网站时，确保在运行 `hugo` 命令之前执行以下命令至关重要。
+当使用[CI/CD](https://en.wikipedia.org/wiki/CI/CD)部署Hugo网站时，确保在运行`hugo`命令之前执行以下命令至关重要。

 ```shell
 git submodule update --init
 ```

-如果不运行此命令，主题文件夹将不会被 Hextra 主题文件填充，导致构建失败。
+如果不运行此命令，主题文件夹将不会被填充Hextra主题文件，导致构建失败。


 {{% details title="如何更新主题？" %}}

-要更新仓库中所有子模块到最新提交，请运行以下命令：
+要更新仓库中的所有子模块到最新提交，运行以下命令：

 ```shell
 git submodule update --remote
 ```

-要将 Hextra 更新到最新提交，请运行以下命令：
+要将Hextra更新到最新提交，运行以下命令：

 ```shell
 git submodule update --remote themes/hextra
 ```

-有关更多详细信息，请参阅 [Git 子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。
+更多详情请参阅[Git子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules)。

 {{% /details %}}

--- a/exampleSite/content/docs/guide/_index.zh-cn.md
+++ b/exampleSite/content/docs/guide/_index.zh-cn.md
@@ -7,7 +7,7 @@ sidebar:
  open: true
 ---

-探索以下部分，了解如何使用 Hextra：
+通过以下章节了解如何使用 Hextra：

 <!--more-->

--- a/exampleSite/content/docs/guide/configuration.zh-cn.md
+++ b/exampleSite/content/docs/guide/configuration.zh-cn.md
@@ -1,11 +1,13 @@
 ---
 title: 配置
 weight: 2
+tags:
+  - 配置
 ---

-Hugo 从您 Hugo 站点根目录下的 `hugo.yaml` 文件中读取配置。
-配置文件是您可以配置站点所有方面的地方。
-查看此站点的配置文件 [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) 在 GitHub 上，以全面了解可用的设置和最佳实践。
+Hugo 从站点根目录的 `hugo.yaml` 读取配置。
+配置文件可用来调整站点的所有方面。
+查看本网站的示例配置文件 [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) 以全面了解可用设置和最佳实践。

 <!--more-->

@@ -13,7 +15,7 @@ Hugo 从您 Hugo 站点根目录下的 `hugo.yaml` 文件中读取配置。

 ### 菜单

-右上角的菜单在配置文件的 `menu.main` 部分中定义：
+右上角菜单在配置文件的 `menu.main` 部分定义：

 ```yaml {filename="hugo.yaml"}
 menu:
@@ -38,19 +40,19 @@ menu:
        icon: github
 ```

-有不同类型的菜单项：
+菜单项有以下几种类型：

-1. 使用 `pageRef` 链接到站点内的页面
+1. 通过 `pageRef` 链接到站内页面
   ```yaml
   - name: 文档
     pageRef: /docs
   ```
-2. 使用 `url` 链接到外部 URL
+2. 通过 `url` 链接到外部网址
   ```yaml
   - name: GitHub
     url: "https://github.com"
   ```
-3. 使用 `type: search` 的搜索栏
+3. 搜索栏，使用 `type: search`
   ```yaml
   - name: 搜索
     params:
@@ -63,12 +65,33 @@ menu:
       icon: github
   ```

-这些菜单项可以通过设置 `weight` 参数进行排序。
+通过设置 `weight` 参数可以调整菜单项的排序。

-### 徽标和标题
+### 嵌套菜单

-要修改默认徽标，编辑 `hugo.yaml` 并在 `static` 目录下添加徽标文件的路径。
-您还可以更改用户点击徽标时重定向的链接，以及设置徽标的宽度和高度（以像素为单位）。
+通过定义子菜单项可以创建下拉菜单。点击父菜单项时会显示子菜单。
+
+```yaml {filename="hugo.yaml"}
+menu:
+  main:
+    - identifier: sdk
+      name: SDK
+    - identifier: python
+      name: Python ↗
+      url: https://python.org
+      parent: sdk
+    - identifier: go
+      name: Go
+      url: https://go.dev
+      parent: sdk
+```
+
+子菜单项需要通过 `parent` 参数指定父菜单的 `identifier` 值。
+
+### 徽标与标题
+
+要修改默认徽标，编辑 `hugo.yaml` 并在 `static` 目录下添加徽标文件路径。
+可选地，可以更改点击徽标时的跳转链接，以及设置徽标的像素宽度和高度。

 ```yaml {filename="hugo.yaml"}
 params:
@@ -87,10 +110,10 @@ params:

 ### 主侧边栏

-主侧边栏是根据内容目录的结构自动生成的。
-有关更多详细信息，请参阅 [组织文件](/docs/guide/organize-files) 页面。
+主侧边栏会根据内容目录结构自动生成。
+详情参见[文件组织](/docs/guide/organize-files)页面。

-要从左侧边栏中排除单个页面，请在页面的 front matter 中设置 `sidebar.exclude` 参数：
+要从左侧边栏排除单个页面，在页面的 front matter 中设置 `sidebar.exclude` 参数：

 ```yaml {filename="content/docs/guide/configuration.md"}
 ---
@@ -102,7 +125,7 @@ sidebar:

 ### 额外链接

-侧边栏的额外链接在配置文件的 `menu.sidebar` 部分中定义：
+侧边栏额外链接在配置文件的 `menu.sidebar` 部分定义：

 ```yaml {filename="hugo.yaml"}
 menu:
@@ -123,7 +146,7 @@ menu:

 ### 目录

-目录是根据内容文件中的标题自动生成的。可以通过在页面的 front matter 中设置 `toc: false` 来禁用它。
+目录会根据内容文件中的标题自动生成。可以通过在页面的 front matter 中设置 `toc: false` 来禁用。

 ```yaml {filename="content/docs/guide/configuration.md"}
 ---
@@ -134,7 +157,7 @@ toc: false

 ### 页面编辑链接

-要配置页面编辑链接，我们可以在配置文件中设置 `params.editURL.base` 参数：
+要配置页面编辑链接，可以在配置文件中设置 `params.editURL.base` 参数：

 ```yaml {filename="hugo.yaml"}
 params:
@@ -143,8 +166,8 @@ params:
    base: "https://github.com/your-username/your-repo/edit/main"
 ```

-编辑链接将根据提供的 URL 作为根目录自动为每个页面生成。
-如果要为特定页面设置编辑链接，可以在页面的 front matter 中设置 `editURL` 参数：
+编辑链接将基于提供的 URL 作为根目录自动为每个页面生成。
+如果想为特定页面设置编辑链接，可以在页面的 front matter 中设置 `editURL` 参数：

 ```yaml {filename="content/docs/guide/configuration.md"}
 ---
@@ -155,22 +178,22 @@ editURL: "https://example.com/edit/this/page"

 ## 页脚

-### 版权
+### 版权信息

-要修改网站页脚中显示的版权文本，您需要创建一个名为 `i18n/en.yaml` 的文件。
-在此文件中，指定您的新版权文本，如下所示：
+要修改网站页脚显示的版权文本，需要创建一个名为 `i18n/en.yaml` 的文件。
+在该文件中指定新的版权文本，如下所示：

 ```yaml {filename="i18n/en.yaml"}
-copyright: "© 2024 您的文本"
+copyright: "© 2024 你的文本内容"
 ```

-作为参考，可以在 GitHub 仓库中找到示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。此外，您可以在版权文本中使用 Markdown 格式。
+可以参考 GitHub 仓库中的示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。此外，可以在版权文本中使用 Markdown 格式。

 ## 其他

 ### 网站图标

-要为您的站点自定义 [网站图标](https://en.wikipedia.org/wiki/Favicon)，请将图标文件放在 `static` 文件夹下，以覆盖 [主题的默认网站图标](https://github.com/imfing/hextra/tree/main/static)：
+要自定义网站的 [favicon](https://en.wikipedia.org/wiki/Favicon)，将图标文件放在 `static` 文件夹下以覆盖[主题默认的网站图标](https://github.com/imfing/hextra/tree/main/static)：

 {{< filetree/container >}}
  {{< filetree/folder name="static" >}}
@@ -186,14 +209,30 @@ copyright: "© 2024 您的文本"
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-在您的项目中包含 `favicon.ico`、`favicon.svg` 和 `favicon-dark.svg` 文件，以确保您的站点图标正确显示。
+#### 基本设置

-虽然 `favicon.ico` 通常用于旧版浏览器，但 `favicon.svg` 和 `favicon-dark.svg` 受现代浏览器支持。
-使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具生成此类图标。
+至少需要在 `static` 文件夹中包含 `favicon.svg`。这将作为网站的默认图标。
+
+可以通过在 SVG 文件中使用 CSS 媒体查询来创建自适应图标，响应系统主题偏好，具体方法参考[构建自适应网站图标](https://web.dev/articles/building/an-adaptive-favicon)。
+
+#### 暗色模式支持
+
+为了增强暗色模式支持，在 `static` 文件夹中添加 `favicon-dark.svg` 与 `favicon.svg` 一起。当两个文件都存在时，Hextra 会自动：
+
+- 在亮色模式或未检测到主题偏好时使用 `favicon.svg`
+- 当用户系统设置为暗色模式时切换到 `favicon-dark.svg`
+- 尊重系统的 `prefers-color-scheme` 设置实现自动切换
+
+暗色模式图标切换在所有现代浏览器中都有效，包括 Firefox，提供与网站主题一致的无缝体验。
+
+#### 其他格式
+
+虽然 `favicon.ico` 通常用于旧版浏览器，现代浏览器支持 SVG 图标，因其可缩放性和小文件大小而更受青睐。
+如果需要，可以使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具生成其他格式的图标。

 ### 主题配置

-使用 `theme` 设置来配置默认主题模式和切换按钮，允许访问者在浅色或深色模式之间切换。
+使用 `theme` 设置来配置默认主题模式和切换按钮，允许访问者在亮色或暗色模式之间切换。

 ```yaml {filename="hugo.yaml"}
 params:
@@ -205,16 +244,32 @@ params:

 `theme.default` 的选项：

- `light` - 始终使用浅色模式
- `dark` - 始终使用深色模式
+- `light` - 始终使用亮色模式
+- `dark` - 始终使用暗色模式
 - `system` - 与操作系统设置同步（默认）

-`theme.displayToggle` 参数允许您显示一个切换按钮以更改主题。
-当设置为 `true` 时，访问者可以在浅色或深色模式之间切换，覆盖默认设置。
+`theme.displayToggle` 参数允许显示主题切换按钮。
+当设置为 `true` 时，访问者可以切换亮色或暗色模式，覆盖默认设置。
+
+### 页面最后修改时间
+
+可以通过启用 `params.displayUpdatedDate` 标志来显示页面的最后修改日期。要使用 Git 提交日期作为来源，还需启用 `enableGitInfo` 标志。
+
+要自定义日期格式，设置 `params.dateFormat` 参数。其布局与 Hugo 的 [`time.Format`](https://gohugo.io/functions/time/format/) 匹配。
+
+```yaml {filename="hugo.yaml"}
+# 解析 Git 提交
+enableGitInfo: true
+
+params:
+  # 显示最后修改日期
+  displayUpdatedDate: true
+  dateFormat: "2006年1月2日"
+```

 ### 标签

-要显示页面标签，请在配置文件中设置以下标志：
+要显示页面标签，在配置文件中设置以下标志：

 ```yaml {filename="hugo.yaml"}
 params:
@@ -227,7 +282,7 @@ params:

 ### 页面宽度

-页面的宽度可以通过配置文件中的 `params.page.width` 参数进行自定义：
+页面宽度可以通过配置文件中的 `params.page.width` 参数自定义：

 ```yaml {filename="hugo.yaml"}
 params:
@@ -236,14 +291,14 @@ params:
    width: wide
 ```

-有三个可用选项：`full`、`wide` 和 `normal`。默认情况下，页面宽度设置为 `normal`。
+有三个可用选项：`full`、`wide` 和 `normal`。默认页面宽度为 `normal`。

-同样，导航栏和页脚的宽度可以通过 `params.navbar.width` 和 `params.footer.width` 参数进行自定义。
+类似地，导航栏和页脚的宽度可以通过 `params.navbar.width` 和 `params.footer.width` 参数自定义。

-### 搜索索引
+### FlexSearch 索引

 默认启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供的全文搜索。
-要自定义搜索索引，请在配置文件中设置 `params.search.flexsearch.index` 参数：
+要自定义搜索索引，在配置文件中设置 `params.search.flexsearch.index` 参数：

 ```yaml {filename="hugo.yaml"}
 params:
@@ -253,21 +308,22 @@ params:
    type: flexsearch

    flexsearch:
-      # 按以下内容索引页面：content | summary | heading | title
+      # 索引页面方式: content | summary | heading | title
      index: content
 ```

 `flexsearch.index` 的选项：

 - `content` - 页面的完整内容（默认）
- `summary` - 页面的摘要，请参阅 [Hugo 内容摘要](https://gohugo.io/content-management/summaries/) 了解更多详细信息
+- `summary` - 页面摘要，详见 [Hugo 内容摘要](https://gohugo.io/content-management/summaries/)
 - `heading` - 一级和二级标题
- `title` - 仅包括页面标题
+- `title` - 仅包含页面标题

-要自定义搜索分词，请在配置文件中设置 `params.search.flexsearch.tokenize` 参数：
+要自定义搜索分词方式，在配置文件中设置 `params.search.flexsearch.tokenize` 参数：

 ```yaml {filename="hugo.yaml"}
 params:
+  search:
    # ...
    flexsearch:
      # full | forward | reverse | strict
@@ -276,12 +332,12 @@ params:

 [`flexsearch.tokenize`](https://github.com/nextapps-de/flexsearch/#tokenizer-prefix-search) 的选项：

- `strict` - 索引整个单词
- `forward` - 向前方向逐步索引单词
+- `strict` - 索引完整单词
+- `forward` - 正向逐步索引单词
 - `reverse` - 双向逐步索引单词
 - `full` - 索引所有可能的组合

-要从搜索索引中排除页面，请在页面的 front matter 中设置 `excludeSearch: true`：
+要从 FlexSearch 搜索索引中排除页面，在页面的 front matter 中设置 `excludeSearch: true`：

 ```yaml {filename="content/docs/guide/configuration.md"}
 ---
@@ -290,12 +346,65 @@ excludeSearch: true
 ---
 ```

-### Google Analytics
+### Google 分析

-要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，请在 `hugo.yaml` 中设置 `services.googleAnalytics.ID` 标志：
+要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，在 `hugo.yaml` 中设置 `services.googleAnalytics.ID` 标志：

 ```yaml {filename="hugo.yaml"}
 services:
  googleAnalytics:
    ID: G-MEASUREMENT_ID
 ```
+
+### Google 搜索索引
+
+要[阻止 Google 搜索](https://developers.google.com/search/docs/crawling-indexing/block-indexing)索引页面，在页面的 frontmatter 中设置 `noindex` 为 true：
+
+```yaml
+title: 配置（存档版本）
+params:
+  noindex: true
+```
+
+要排除整个目录，在父级 `_index.md` 文件中使用 [`cascade`](https://gohugo.io/configuration/cascade/) 键。
+
+> [!注意]
+> 要阻止搜索引擎爬虫，可以制作 [`robots.txt` 模板](https://gohugo.io/templates/robots/)。
+> 但是，`robots.txt` 指令不一定能阻止页面出现在 Google 搜索结果中。
+
+### LLMS.txt 支持
+
+要为网站启用 [llms.txt](https://llmstxt.org/) 输出格式，为[大型语言模型](https://en.wikipedia.org/wiki/Large_language_model)和 AI 代理提供结构化文本大纲，在站点的 `hugo.yaml` 中添加 `llms` 输出格式：
+
+```diff {filename="hugo.yaml"}
+outputs:
+- home: [html]
+ home: [html, llms]
+  page: [html]
+  section: [html, rss]
+```
+
+这将在站点根目录生成一个 `llms.txt` 文件，包含：
+
+- 站点标题和描述
+- 所有章节和页面的层次结构列表
+- 页面摘要和发布日期
+- 所有内容的直接链接
+
+llms.txt 文件根据内容结构自动生成，使 AI 工具和语言模型更容易获取上下文和参考。
+
+### Open Graph
+
+要在页面中添加 [Open Graph](https://ogp.me/) 元数据，在 frontmatter 的 params 中添加值。
+
+由于一个页面可以有多个 `image` 和 `video` 标签，将它们的值放在数组中。
+其他 Open Graph 属性只能有一个值。
+例如，此页面有一个 `og:image` 标签（配置社交分享时的预览图片）和一个 `og:audio` 标签。
+
+```yaml {filename="content/docs/guide/configuration.md"}
+title: "配置"
+params:
+  images:
+    - "/img/config-image.jpg"
+  audio: "config-talk.mp3"
+```
--- a/exampleSite/content/docs/guide/deploy-site.zh-cn.md
+++ b/exampleSite/content/docs/guide/deploy-site.zh-cn.md
@@ -4,42 +4,42 @@ prev: /docs/guide/shortcodes
 next: /docs/advanced
 ---

-Hugo 生成静态网站，允许灵活的托管选项。
-本页提供了在各种平台上部署 Hextra 站点的指南。
+Hugo 生成静态网站，支持灵活的托管方案。
+本页提供在各类平台上部署 Hextra 站点的指南。

 <!--more-->


 ## GitHub Pages

-[GitHub Pages](https://docs.github.com/pages) 是推荐的方式，可以免费部署和托管您的网站。
+[GitHub Pages](https://docs.github.com/pages) 是推荐的免费部署托管方案。

-如果您使用 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 引导站点，它已经提供了开箱即用的 GitHub Actions 工作流，帮助自动部署到 GitHub Pages。
+若使用 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 初始化项目，已内置 GitHub Actions 工作流，可自动部署至 GitHub Pages。

 {{% details title="GitHub Actions 配置" closed="true" %}}

 以下是 [hextra-starter-template](https://github.com/imfing/hextra-starter-template) 的示例配置：

 ```yaml {filename=".github/workflows/pages.yaml"}
-# 用于构建和部署 Hugo 站点到 GitHub Pages 的示例工作流
+# 构建并部署 Hugo 站点到 GitHub Pages 的示例工作流
 name: 部署 Hugo 站点到 Pages

 on:
-  # 在推送到默认分支时运行
+  # 针对默认分支的推送触发
  push:
    branches: ["main"]

-  # 允许您从 Actions 选项卡手动运行此工作流
+  # 允许从 Actions 标签手动运行
  workflow_dispatch:

-# 设置 GITHUB_TOKEN 的权限以允许部署到 GitHub Pages
+# 设置 GITHUB_TOKEN 权限以允许部署到 GitHub Pages
 permissions:
  contents: read
  pages: write
  id-token: write

-# 只允许一个并发部署，跳过在运行中和最新排队之间的运行。
-# 但是，不要取消正在运行的运行，因为我们希望这些生产部署能够完成。
+# 仅允许一个并发部署，跳过正在运行与最新排队之间的运行
+# 但不会取消进行中的运行，以确保生产部署完成
 concurrency:
  group: "pages"
  cancel-in-progress: false
@@ -56,32 +56,32 @@ jobs:
    env:
      HUGO_VERSION: 0.147.7
    steps:
-      - name: 检出
+      - name: 检出代码
        uses: actions/checkout@v4
        with:
-          fetch-depth: 0  # 获取所有历史记录以支持 .GitInfo 和 .Lastmod
+          fetch-depth: 0  # 获取完整历史记录以支持 .GitInfo 和 .Lastmod
          submodules: recursive
-      - name: 设置 Go
+      - name: 设置 Go 环境
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
-      - name: 设置 Pages
+      - name: 配置 Pages
        id: pages
        uses: actions/configure-pages@v4
-      - name: 设置 Hugo
+      - name: 安装 Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: 使用 Hugo 构建
        env:
-          # 为了最大程度地兼容 Hugo 模块
+          # 为 Hugo 模块提供最大兼容性
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
-      - name: 上传工件
+      - name: 上传产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
@@ -103,13 +103,13 @@ jobs:


 {{< callout >}}
-  在您的仓库设置中，将 **Pages** > **Build and deployment** > **Source** 设置为 **GitHub Actions**：
+  在仓库设置中，将 **Pages** > **构建与部署** > **源** 设为 **GitHub Actions**：
  ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png)
 {{< /callout >}}

-默认情况下，上述 GitHub Actions 工作流 `.github/workflows/pages.yaml` 假设站点部署到 `https://<USERNAME>.github.io/<REPO>/`。
+默认配置中，GitHub Actions 工作流 `.github/workflows/pages.yaml` 假设站点部署在 `https://<用户名>.github.io/<仓库名>/`。

-如果您部署到 `https://<USERNAME>.github.io/`，请修改 `--baseURL`：
+若需部署到 `https://<用户名>.github.io/`，请修改 `--baseURL`：

 ```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
 run: |
@@ -118,47 +118,47 @@ run: |
    --baseURL "https://${{ github.repository_owner }}.github.io/"
 ```

-如果您部署到自己的域名，请相应地更改 `--baseURL` 值。
+若使用自定义域名，请相应调整 `--baseURL` 值。


 ## Cloudflare Pages

-1. 将您的站点源代码放入 Git 仓库（例如 GitHub）
-2. 登录 [Cloudflare 仪表板](https://dash.cloudflare.com/) 并选择您的账户
-3. 在账户主页中，选择 **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**
-4. 选择仓库，并在 **Set up builds and deployments** 部分提供以下信息：
+1. 将站点源码存入 Git 仓库（如 GitHub）
+2. 登录 [Cloudflare 控制台](https://dash.cloudflare.com/) 并选择账户
+3. 在账户首页选择 **Workers & Pages** > **创建应用** > **Pages** > **连接 Git**
+4. 选择仓库后，在 **设置构建与部署** 部分填写：

 | 配置项           | 值                   |
-| ------------------ | -------------------- |
+| ---------------- | -------------------- |
 | 生产分支         | `main`               |
 | 构建命令         | `hugo --gc --minify` |
-| 构建目录           | `public`             |
+| 构建输出目录     | `public`             |

-更多详情，请查看：
- [部署 Hugo 站点](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages)。
- [语言支持和工具](https://developers.cloudflare.com/pages/platform/language-support-and-tools/)。
+更多细节请参阅：
+- [部署 Hugo 站点](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages)
+- [语言支持与工具](https://developers.cloudflare.com/pages/platform/language-support-and-tools/)


 ## Netlify

-1. 将代码推送到您的 Git 仓库（GitHub、GitLab 等）
-2. [导入项目](https://app.netlify.com/start) 到 Netlify
-3. 如果您没有使用 [hextra-starter-template][hextra-starter-template]，请手动配置以下内容：
-   - 将构建命令配置为 `hugo --gc --minify`
-   - 指定发布目录为 `public`
-   - 添加环境变量 `HUGO_VERSION` 并设置为 `0.147.7`，或者将其设置在 `netlify.toml` 文件中
-4. 部署！
+1. 将代码推送到 Git 仓库（GitHub/GitLab 等）
+2. 在 Netlify 中[导入项目](https://app.netlify.com/start)
+3. 若未使用 [hextra-starter-template][hextra-starter-template]，需手动配置：
+   - 构建命令设为 `hugo --gc --minify`
+   - 发布目录设为 `public`
+   - 添加环境变量 `HUGO_VERSION` 并设为 `0.147.7`，或在 `netlify.toml` 中配置
+4. 开始部署！

-查看 [Netlify 上的 Hugo](https://docs.netlify.com/integrations/frameworks/hugo/) 了解更多详情。
+详见 [Netlify 上的 Hugo](https://docs.netlify.com/integrations/frameworks/hugo/)


 ## Vercel

-1. 将代码推送到您的 Git 仓库（GitHub、GitLab 等）
-2. 前往 [Vercel 仪表板](https://vercel.com/dashboard) 并导入您的 Hugo 项目
-3. 配置项目，选择 Hugo 作为框架预设
-4. 覆盖构建命令和安装命令：
-   1. 将构建命令设置为 `hugo --gc --minify`
-   2. 将安装命令设置为 `yum install golang`
+1. 将代码推送到 Git 仓库（GitHub/GitLab 等）
+2. 进入 [Vercel 控制台](https://vercel.com/dashboard) 导入 Hugo 项目
+3. 配置项目时选择 Hugo 作为框架预设
+4. 覆盖构建命令与安装命令：
+   1. 构建命令设为 `hugo --gc --minify`
+   2. 安装命令设为 `yum install golang`

 ![Vercel 部署配置](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3)
--- a/exampleSite/content/docs/guide/diagrams.zh-cn.md
+++ b/exampleSite/content/docs/guide/diagrams.zh-cn.md
@@ -4,13 +4,13 @@ weight: 6
 next: /docs/guide/shortcodes
 ---

-目前，Hextra 支持使用 [Mermaid](#mermaid) 来绘制图表。
+目前，Hextra 支持通过 [Mermaid](#mermaid) 绘制图表。

 <!--more-->

 ## Mermaid

-[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表工具，它通过类似 Markdown 的文本定义，在浏览器中动态生成图表。例如，Mermaid 可以渲染流程图、序列图、饼图等。
+[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它能将类 Markdown 的文本定义动态转换为浏览器中渲染的图表。例如，Mermaid 可以绘制流程图、时序图、饼图等多种图表。

 在 Hextra 中使用 Mermaid 非常简单，只需编写一个语言设置为 `mermaid` 的代码块：

@@ -24,7 +24,7 @@ graph TD;
 ```
 ````

-将会渲染为：
+上述代码将渲染为：

 ```mermaid
 graph TD;
@@ -34,7 +34,7 @@ graph TD;
    C-->D;
 ```

-序列图示例：
+时序图示例：

 ```mermaid
 sequenceDiagram
@@ -42,12 +42,12 @@ sequenceDiagram
    participant Bob
    Alice->>John: 你好 John，最近怎么样？
    loop 健康检查
-        John->>John: 与疑病症作斗争
+        John->>John: 与疑病症斗争
    end
    Note right of John: 理性思考 <br/>占据上风！
-    John-->>Alice: 很好！
+    John-->>Alice: 好极了！
    John->>Bob: 你怎么样？
    Bob-->>John: 非常好！
 ```

-更多信息，请参考 [Mermaid 文档](https://mermaid-js.github.io/mermaid/#/)。
+更多信息请参阅 [Mermaid 官方文档](https://mermaid-js.github.io/mermaid/#/)。
--- a/exampleSite/content/docs/guide/latex.zh-cn.md
+++ b/exampleSite/content/docs/guide/latex.zh-cn.md
@@ -1,35 +1,37 @@
 ---
 title: "数学公式"
 weight: 4
-math: true
 ---

-默认情况下，\(\KaTeX\) 用于渲染 LaTeX 数学表达式。
-无需手动激活，您可以直接在 Markdown 内容中开始使用 LaTeX 数学表达式。
+LaTeX 数学表达式默认使用 \(\KaTeX\) 渲染。直接在 Markdown 内容中使用即可，无需手动配置。

-## 示例
+## 使用方法

-Markdown 内容中支持内联和独立段落的 LaTeX 数学表达式。
+LaTeX 既可用于行内表达式，也可用于大段文本。

-### 内联
+### 行内公式
+
+要在文本行内插入表达式，用 `\(` 和 `\)` 包裹。

 ```markdown {filename="page.md"}
-这个 \(\sigma(z) = \frac{1}{1 + e^{-z}}\) 是内联的。
+这个 \(\sigma(z) = \frac{1}{1 + e^{-z}}\) 是行内表达式。
 ```

-这个 \(\sigma(z) = \frac{1}{1 + e^{-z}}\) 是内联的。
+这个 \( \sigma(z) = \frac{1}{1 + e^{-z}} \) 是行内表达式。

-### 独立段落
+### 独立公式
+
+对于需要单独成段的表达式，使用 `$$` 包裹。

 ```markdown {filename="page.md"}
-$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
 ```

 将渲染为：

-$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$

-例如，使用对齐环境：
+还可以使用 LaTeX 环境如 `aligned` 处理多行公式。

 ```latex {filename="page.md"}
 $$
@@ -53,11 +55,28 @@ $$
 \end{aligned}
 $$

+支持的函数列表见 [KaTeX 支持函数](https://katex.org/docs/supported.html)。
+
+### 化学表达式
+
+默认启用了 [mhchem][mhchem] 扩展，可轻松渲染化学方程式和分子式。
+
+行内示例：\(\ce{H2O}\) 是水。
+
+独立段落：
+
+```markdown {filename="page.md"}
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```
+
+将渲染为：
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$

 ## 配置

 > [!IMPORTANT]
-> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)，以便 Hugo 可以检测 Markdown 内容中的 LaTeX 数学表达式。
+> 请在 Hugo 配置文件中启用并配置 [passthrough 扩展](https://gohugo.io/content-management/mathematics/)，以便 Hugo 能识别 Markdown 中的 LaTeX 数学表达式。

 ```yaml {filename="hugo.yaml"}
 markup:
@@ -70,35 +89,46 @@ markup:
        enable: true
 ```

-## 支持的函数
+### 数学引擎

-有关支持的函数列表，请参阅 [KaTeX 支持的函数](https://katex.org/docs/supported.html)。
+构建过程中默认使用 [KaTeX][katex] 渲染 LaTeX 数学表达式，由 [Hugo][hugo-transform-tomath] 支持。

-## 化学
+默认引擎是 KaTeX，但也可切换至 [MathJax][mathjax] 以使用其特有功能。

-通过 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 扩展支持化学表达式。
+#### KaTeX

-内联：\(\ce{H2O}\) 是水。
+默认设置无需配置。Hugo 会从 CDN 获取 KaTeX CSS。如需指定 KaTeX 版本或使用本地资源，可在 `hugo.yaml` 中配置。

-独立段落：
+##### 覆盖 CDN 基础 URL

-```markdown {filename="page.md"}
-$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: katex
+    katex:
+      base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
 ```

-将渲染为：
+##### 使用本地资源

-$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+可将 CSS 文件置于 `assets` 目录，并发布 KaTeX 所需的字体文件。

+```yaml {filename="hugo.yaml"}
+params:
+  math:
+    engine: katex
+    katex:
+      css: "css/katex.min.css"
+      assets:
+        - "fonts/KaTeX_Main-Regular.woff2"
+        # 在此添加其他字体文件
+```

-## 数学引擎
+此时将从 `assets/css/katex.min.css` 加载 KaTeX CSS 文件，而非从 CDN 下载。

-### MathJax
+#### MathJax

-默认情况下，使用 [KaTeX][katex] 在构建过程中渲染 LaTeX 数学表达式，这是首选方式。
-或者，您可以使用 [MathJax][mathjax] 来渲染数学表达式。
-
-要使用 MathJax，请将以下内容添加到 `hugo.yaml` 配置文件中：
+也可使用 [MathJax][mathjax] 渲染数学表达式：

 ```yaml {filename="hugo.yaml"}
 params:
@@ -106,5 +136,10 @@ params:
    engine: mathjax
 ```

+> [!NOTE]
+> 可通过在项目中覆盖 `layouts/_partials/scripts/mathjax.html` 模板进一步定制 MathJax（如调整加载器选项或更改 CDN/源）。Hugo 将优先使用你的版本而非主题默认配置。
+
 [katex]: https://katex.org/
 [mathjax]: https://www.mathjax.org/
+[mhchem]: https://mhchem.github.io/MathJax-mhchem/
+[hugo-transform-tomath]: https://gohugo.io/functions/transform/tomath/
--- a/exampleSite/content/docs/guide/markdown.zh-cn.md
+++ b/exampleSite/content/docs/guide/markdown.zh-cn.md
@@ -3,7 +3,7 @@ title: Markdown
 weight: 2
 ---

-Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来格式化文本、创建列表等。本页将展示一些最常见的 Markdown 语法示例。
+Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来格式化文本、创建列表等。本页将展示一些最常用的 Markdown 语法示例。

 <!--more-->

@@ -12,27 +12,27 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来
 ### 文本样式

 | 样式   | 语法             | 示例                      | 输出                    |
-| --------  | -------- | ------ | ------ |
+| :----- | :--------------- | :------------------------ | :---------------------- |
 | 粗体   | `**粗体文本**`   | `**粗体文本**`            | **粗体文本**            |
-| 斜体 | `*斜体文本*` | `*斜体文本*` | *斜体文本* |
+| 斜体   | `*斜体文本*`     | `*斜体文本*`              | _斜体文本_              |
 | 删除线 | `~~删除线文本~~` | `~~删除线文本~~`          | ~~删除线文本~~          |
-| 下标 | `<sub></sub>` | `这是一个<sub>下标</sub>文本` | 这是一个<sub>下标</sub>文本 |
-| 上标 | `<sup></sup>` | `这是一个<sup>上标</sup>文本` | 这是一个<sup>上标</sup>文本 |
+| 下标   | `<sub></sub>`    | `这是<sub>下标</sub>文本` | 这是<sub>下标</sub>文本 |
+| 上标   | `<sup></sup>`    | `这是<sup>上标</sup>文本` | 这是<sup>上标</sup>文本 |

 ### 引用块

-带出处的引用块
+带出处的引用

 > 不要通过共享内存来通信，而要通过通信来共享内存。<br>
 > — <cite>Rob Pike[^1]</cite>

-[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
+[^1]: 上述引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。

 ```markdown {filename=Markdown}
 > 不要通过共享内存来通信，而要通过通信来共享内存。<br>
 > — <cite>Rob Pike[^1]</cite>

-[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
+[^1]: 上述引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。
 ```

 ### 提示框
@@ -44,63 +44,63 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来
 请确保您使用的是最新版本的 Hextra 和 [Hugo v0.146.0](https://github.com/gohugoio/hugo/releases/tag/v0.146.0) 或更高版本。

 > [!NOTE]
-> 用户应该知道的有用信息，即使是在浏览内容时。
+> 即使用户只是浏览内容，也应该知道的有用信息。

 > [!TIP]
-> 帮助用户更好地或更轻松地完成任务的建议。
+> 帮助用户更高效或更轻松完成任务的建议。

 > [!IMPORTANT]
 > 用户需要了解的关键信息，以实现他们的目标。

 > [!WARNING]
-> 需要用户立即注意的紧急信息，以避免问题。
+> 需要用户立即关注的紧急信息，以避免出现问题。

 > [!CAUTION]
-> 关于某些操作的风险或负面结果的建议。
+> 关于某些操作可能带来风险或负面结果的警告。

 ```markdown {filename=Markdown}
 > [!NOTE]
-> 用户应该知道的有用信息，即使是在浏览内容时。
+> 即使用户只是浏览内容，也应该知道的有用信息。

 > [!TIP]
-> 帮助用户更好地或更轻松地完成任务的建议。
+> 帮助用户更高效或更轻松完成任务的建议。

 > [!IMPORTANT]
 > 用户需要了解的关键信息，以实现他们的目标。

 > [!WARNING]
-> 需要用户立即注意的紧急信息，以避免问题。
+> 需要用户立即关注的紧急信息，以避免出现问题。

 > [!CAUTION]
-> 关于某些操作的风险或负面结果的建议。
+> 关于某些操作可能带来风险或负面结果的警告。
 ```

 ### 表格

-表格不是 Markdown 核心规范的一部分，但 Hugo 默认支持它们。
+表格不是 Markdown 核心规范的一部分，但 Hugo 原生支持它们。

 | 姓名 | 年龄 |
-|--------|------|
-|    Bob | 27   |
-|  Alice | 23   |
+| :--- | :--- |
+| 张三 | 27   |
+| 李四 | 23   |

 ```markdown {filename=Markdown}
 | 姓名 | 年龄 |
-|--------|------|
-|    Bob | 27   |
-|  Alice | 23   |
+| :--- | :--- |
+| 张三 | 27   |
+| 李四 | 23   |
 ```

-#### 表格中的内联 Markdown
+#### 表格内的行内 Markdown

 | 斜体   | 粗体     | 代码   |
-| --------  | -------- | ------ |
-| *斜体* | **粗体** | `代码` |
+| :----- | :------- | :----- |
+| _斜体_ | **粗体** | `代码` |

 ```markdown {filename=Markdown}
 | 斜体   | 粗体     | 代码   |
-| --------  | -------- | ------ |
-| *斜体* | **粗体** | `代码` |
+| :----- | :------- | :----- |
+| _斜体_ | **粗体** | `代码` |
 ```

 ### 代码块
@@ -125,34 +125,34 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来

 #### 无序列表

-* 列表项
-* 另一个项
-* 再一个项
+- 列表项
+- 另一个项
+- 再一个项

 ```markdown {filename=Markdown}
-* 列表项
-* 另一个项
-* 再一个项
+- 列表项
+- 另一个项
+- 再一个项
 ```

 #### 嵌套列表

-* 水果
-  * 苹果
-  * 橙子
-  * 香蕉
-* 乳制品
-  * 牛奶
-  * 奶酪
+- 水果
+  - 苹果
+  - 橙子
+  - 香蕉
+- 乳制品
+  - 牛奶
+  - 奶酪

 ```markdown {filename=Markdown}
-* 水果
-  * 苹果
-  * 橙子
-  * 香蕉
-* 乳制品
-  * 牛奶
-  * 奶酪
+- 水果
+  - 苹果
+  - 橙子
+  - 香蕉
+- 乳制品
+  - 牛奶
+  - 奶酪
 ```

 ### 图片
@@ -165,16 +165,18 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来

 带标题：

-![风景](https://picsum.photos/800/600 "Unsplash 风景")
+![风景](https://picsum.photos/800/600 "Lorem Picsum")

 ```markdown {filename=Markdown}
-![风景](https://picsum.photos/800/600 "Unsplash 风景")
+![风景](https://picsum.photos/800/600 "Lorem Picsum")
 ```

+如需更高级的功能，请使用 Hugo 内置的 [Figure 短代码](https://gohugo.io/shortcodes/figure/)。
+
 ## 配置

 Hugo 使用 [Goldmark](https://github.com/yuin/goldmark) 进行 Markdown 解析。
-Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 下进行配置。
+Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 下配置。
 以下是 Hextra 的默认配置：

 ```yaml {filename="hugo.yaml"}
@@ -190,7 +192,7 @@ markup:

 ## 学习资源

-* [Markdown 指南](https://www.markdownguide.org/)
-* [Markdown 速查表](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-* [Markdown 教程](https://www.markdowntutorial.com/)
-* [Markdown 参考](https://commonmark.org/help/)
+- [Markdown 指南](https://www.markdownguide.org/)
+- [Markdown 速查表](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+- [Markdown 教程](https://www.markdowntutorial.com/)
+- [Markdown 参考](https://commonmark.org/help/)
--- a/exampleSite/content/docs/guide/organize-files.zh-cn.md
+++ b/exampleSite/content/docs/guide/organize-files.zh-cn.md
@@ -1,5 +1,5 @@
 ---
-title: 组织文件
+title: 文件组织
 weight: 1
 prev: /docs/guide
 ---
@@ -29,7 +29,7 @@ prev: /docs/guide
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-每个 `_index.md` 文件都是对应部分的索引页面。其他 Markdown 文件则是常规页面。
+每个 `_index.md` 文件都是对应部分的索引页。其他 Markdown 文件则是常规页面。

 ```
 content
@@ -49,13 +49,13 @@ content

 Hextra 为不同类型的内容提供了三种布局：

-| 布局      | 目录               | 特性                                                         |
-| :-------- | :------------------ | :----------------------------------------------------------- |
+| 布局      | 目录               | 特点                                                           |
+| :-------- | :----------------- | :------------------------------------------------------------- |
 | `docs`    | `content/docs/`    | 适合结构化文档，与本部分相同。                                 |
 | `blog`    | `content/blog/`    | 用于博客文章，包含列表和详细文章视图。                         |
 | `default` | 其他所有目录       | 单页文章视图，无侧边栏。                                       |

-要将某个部分自定义为与内置布局相同的行为，可以在该部分的 `_index.md` 的前言中指定所需的类型。
+要自定义一个部分以模仿内置布局的行为，可以在该部分的 `_index.md` 的 front matter 中指定所需的类型。

 ```yaml {filename="content/my-docs/_index.md"}
 ---
@@ -65,11 +65,11 @@ cascade:
 ---
 ```

-上述示例配置确保 `content/my-docs/` 中的内容文件默认会被视为文档（`docs` 类型）。
+上述示例配置确保 `content/my-docs/` 内的内容文件默认会被视为文档（`docs` 类型）。

 ## 侧边栏导航

-侧边栏导航会根据内容组织按字母顺序自动生成。要手动配置侧边栏顺序，可以在 Markdown 文件的前言中使用 `weight` 参数。
+侧边栏导航会根据内容组织按字母顺序自动生成。要手动配置侧边栏顺序，可以在 Markdown 文件的 front matter 中使用 `weight` 参数。

 ```yaml {filename="content/docs/guide/_index.md"}
 ---
@@ -79,14 +79,83 @@ weight: 2
 ```

 {{< callout emoji="ℹ️">}}
-  建议不要让侧边栏过深。如果你有很多内容，考虑**将它们分成多个部分**。
+  建议不要让侧边栏过深。如果有大量内容，可以考虑**将其拆分为多个部分**。
 {{< /callout >}}

+## 部分导航
+
+### 部分分页顺序
+
+通过 [`PAGE.PrevInSection`](https://gohugo.io/methods/page/previnsection/) 和 [`PAGE.NextInSection`](https://gohugo.io/methods/page/nextinsection/) 访问的页面在[页面集合](https://gohugo.io/quick-reference/glossary/#page-collection)中的顺序默认是反向的。
+
+要禁用这种反向排序，可以在页面的 front matter 中将 `reversePagination` 自定义参数设置为 `false`。默认情况下，`reversePagination` 设置为 `true`。
+
+#### 示例
+
+给定以下目录结构：
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/file name="_index.md" >}}
+    {{< filetree/folder name="blog" state="open" >}}
+      {{< filetree/file name="_index.md" >}}
+      {{< filetree/folder name="my-blog-series" state="open" >}}
+        {{< filetree/file name="_index.md" >}}
+        {{< filetree/folder name="post-a" state="open" >}}
+          {{< filetree/file name="index.md" >}}
+        {{< /filetree/folder >}}
+        {{< filetree/folder name="post-b" state="open" >}}
+          {{< filetree/file name="index.md" >}}
+        {{< /filetree/folder >}}
+        {{< filetree/folder name="post-c" state="open" >}}
+          {{< filetree/file name="index.md" >}}
+        {{< /filetree/folder >}}
+      {{< /filetree/folder >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+并在文章的 front matter 中设置：
+
+```yaml {filename="content/blog/my-blog-series/post-a/index.md"}
+---
+title: 文章 A
+weight: 1
+---
+```
+```yaml {filename="content/blog/my-blog-series/post-b/index.md"}
+---
+title: 文章 B
+weight: 2
+---
+```
+```yaml {filename="content/blog/my-blog-series/post-c/index.md"}
+---
+title: 文章 C
+weight: 3
+---
+```
+
+如果读者位于 `post-b/index.md` 的底部，他们会看到下一页是 `post-a`，上一页是 `post-c`。这是由于 `reversePagination` 默认设置为 `true`。当我们希望文章按从最新到最旧的顺序显示时，这是可以的。然而，对于多部分的博客系列，我们通常希望读者先阅读第一部分，然后依次阅读后续部分。因此，我们希望禁用反向排序。
+
+我们可以通过在 `my-blog-series/_index.md` 中添加以下 front matter 来关闭该系列中所有博客文章的 `reversePagination`：
+
+```yaml {filename="content/blog/my-blog-series/_index.md"}
+---
+title: 我的博客系列
+cascade:
+    params:
+        reversePagination: false
+---
+```
+
+这里我们使用 [`cascade`](https://gohugo.io/content-management/front-matter/#cascade-1) 将设置传播到 `my-blog-series` 中的所有文章，以便所有后代都将 `reversePagination` 设置为 `false`。这将确保当读者在 `post-b/index.md` 时，他们会看到下一页是 `post-c`，上一页是 `post-a`。
+
 ## 面包屑导航

-面包屑导航会根据 `/content` 的目录结构自动生成。
+面包屑会根据 `/content` 的目录结构自动生成。

-例如，考虑上面[展示的目录结构](#directory-structure)。根据该结构，页面 `/docs/guide/organize-files/` 顶部的面包屑导航会自动显示如下：
+例如，考虑[上面展示的](#directory-structure)文件结构。给定该结构，位于 `/docs/guide/organize-files/` 的页面顶部的面包屑会自动显示如下：

 ```
 文档 > 指南 > 组织文件
@@ -94,7 +163,7 @@ weight: 2

 ### 自定义面包屑链接标题

-默认情况下，每个面包屑链接是根据页面的 `title` 参数生成的。你可以通过指定 `linkTitle` 来自定义。
+默认情况下，每个面包屑链接是根据该页面的 `title` 参数生成的。可以通过指定 `linkTitle` 来自定义。

 例如，如果我们希望面包屑显示为 `Foo Bar` 而不是 `Organize Files`：

@@ -112,7 +181,7 @@ title: 组织文件

 ### 隐藏面包屑

-你可以通过在页面的前言中指定 `breadcrumbs: false` 来完全隐藏面包屑：
+可以通过在页面的 front matter 中指定 `breadcrumbs: false` 来完全隐藏面包屑：

 ```yaml {filename="content/docs/guide/organize-files.md"}
 ---
@@ -124,11 +193,11 @@ title: 组织文件
 ## 配置内容目录

 默认情况下，Hugo 使用根目录 `content/` 来构建网站。
-如果你需要使用不同的目录来存放内容，例如 `docs/`，可以通过在站点配置文件 `hugo.yaml` 中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 参数来实现。
+如果需要使用其他目录作为内容目录，例如 `docs/`，可以在站点配置 `hugo.yaml` 中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 参数。

 ## 添加图片

-添加图片的最简单方法是将图片文件放在与 Markdown 文件相同的目录中。
+添加图片最简单的方法是将图片文件放在与 Markdown 文件相同的目录中。
 例如，将图片文件 `image.png` 与 `my-page.md` 文件放在一起：

 {{< filetree/container >}}
@@ -140,13 +209,13 @@ title: 组织文件
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-然后，我们可以使用以下 Markdown 语法将图片添加到内容中：
+然后，可以使用以下 Markdown 语法将图片添加到内容中：

 ```markdown {filename="content/docs/my-page.md"}
 ![](image.png)
 ```

-我们还可以利用 Hugo 的 [页面包][page-bundles] 功能将图片文件与 Markdown 文件一起组织。为此，将 `my-page.md` 文件转换为目录 `my-page`，并将内容放入名为 `index.md` 的文件中，然后将图片文件放入 `my-page` 目录中：
+我们还可以利用 Hugo 的[页面包][page-bundles]功能将图片文件与 Markdown 文件组织在一起。为此，将 `my-page.md` 文件转换为目录 `my-page`，并将内容放入名为 `index.md` 的文件中，然后将图片文件放入 `my-page` 目录中：

 {{< filetree/container >}}
  {{< filetree/folder name="content" >}}
@@ -178,7 +247,7 @@ title: 组织文件
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-注意，图片路径以斜杠 `/` 开头，并且相对于静态目录：
+注意，图片路径以斜杠 `/` 开头，并且相对于 static 目录：

 ```markdown {filename="content/docs/my-page.md"}
 ![](/images/image.png)
--- a/exampleSite/content/docs/guide/shortcodes/_index.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/_index.zh-cn.md
@@ -5,12 +5,12 @@ prev: /docs/guide/diagrams
 next: /docs/guide/shortcodes/callout
 ---

-[Hugo 短代码](https://gohugo.io/content-management/shortcodes/)是内容文件中的简单片段，用于调用内置或自定义模板。
+[Hugo 短代码](https://gohugo.io/content-management/shortcodes/)是内容文件中调用内置或自定义模板的简单片段。

-Hextra 提供了一系列精美的短代码，以增强您的内容。
+Hextra 提供了一系列精美的短代码来增强您的内容。

 {{< cards >}}
-  {{< card link="callout" title="标注" icon="warning" >}}
+  {{< card link="callout" title="提示框" icon="warning" >}}
  {{< card link="cards" title="卡片" icon="card" >}}
  {{< card link="details" title="详情" icon="chevron-right" >}}
  {{< card link="filetree" title="文件树" icon="folder-tree" >}}
--- a/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md
@@ -2,7 +2,7 @@
 title: 提示框组件
 linkTitle: 提示框
 aliases:
- 提示框
+- callouts
 prev: /docs/guide/shortcodes
 ---

@@ -11,73 +11,73 @@ prev: /docs/guide/shortcodes
 <!--more-->

 > [!NOTE]
-> 自 [v0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0) 起支持 [GitHub 风格的提醒](../../markdown#alerts)。
-> 它利用 Markdown 语法来渲染提示框，确保内容具有更好的可移植性和可读性。
+> 自 [v0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0) 起支持 [GitHub风格提示框](../../markdown#alerts)。
+> 它利用Markdown语法渲染提示框，确保内容具有更好的可移植性和可读性。

 ## 示例

 {{< callout emoji="👾">}}
-  **提示框** 是一段简短的文本，旨在吸引注意力。
+  **提示框**是一段旨在吸引注意力的简短文本。
 {{< /callout >}}

 {{< callout type="info" >}}
-  **提示框** 是一段简短的文本，旨在吸引注意力。
+  **提示框**是一段旨在吸引注意力的简短文本。
 {{< /callout >}}

 {{< callout type="warning" >}}
-  **提示框** 是一段简短的文本，旨在吸引注意力。
+  **提示框**是一段旨在吸引注意力的简短文本。
 {{< /callout >}}

 {{< callout type="error" >}}
-  **提示框** 是一段简短的文本，旨在吸引注意力。
+  **提示框**是一段旨在吸引注意力的简短文本。
 {{< /callout >}}

-## 用法
+## 使用方法

-### 默认
+### 默认样式

 {{< callout emoji="🌐">}}
-  Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。
+  Hugo可用于创建各种类型的网站，包括博客、作品集、文档站点等。
 {{< /callout >}}

 ```markdown
 {{</* callout emoji="🌐" */>}}
-  Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。
+  Hugo可用于创建各种类型的网站，包括博客、作品集、文档站点等。
 {{</* /callout */>}}
 ```

-### 信息
+### 信息提示

 {{< callout type="info" >}}
-  请访问 GitHub 查看最新版本。
+  请访问GitHub查看最新发布版本。
 {{< /callout >}}

 ```markdown
 {{</* callout type="info" */>}}
-  请访问 GitHub 查看最新版本。
+  请访问GitHub查看最新发布版本。
 {{</* /callout */>}}
 ```

-### 警告
+### 警告提示

 {{< callout type="warning" >}}
-  此 API 将在下一个版本中弃用。
+  此API将在下一版本中弃用。
 {{< /callout >}}

 ```markdown
 {{</* callout type="warning" */>}}
-  **提示框** 是一段简短的文本，旨在吸引注意力。
+  此API将在下一版本中弃用。
 {{</* /callout */>}}
 ```

-### 错误
+### 错误提示

 {{< callout type="error" >}}
-  出错了，系统即将崩溃。
+  出现错误，系统即将崩溃。
 {{< /callout >}}

 ```markdown
 {{</* callout type="error" */>}}
-  出错了，系统即将崩溃。
+  出现错误，系统即将崩溃。
 {{</* /callout */>}}
 ```
--- a/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md
@@ -14,10 +14,10 @@ linkTitle: 卡片
 {{< cards >}}
  {{< card link="/" title="图片卡片" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="网络图片" >}}
  {{< card link="/" title="本地图片" image="/images/card-image-unprocessed.jpg" subtitle="静态目录下的原始图片。" >}}
-  {{< card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，由 Hugo 处理。" method="Resize" options="600x q80 webp" >}}
+  {{< card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，经过Hugo处理。" method="Resize" options="600x q80 webp" >}}
 {{< /cards >}}

-## 用法
+## 使用方法

 ```
 {{</* cards */>}}
@@ -29,9 +29,9 @@ linkTitle: 卡片

 ```
 {{</* cards */>}}
-  {{</* card link="/" title="图片卡片" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash 风景" */>}}
+  {{</* card link="/" title="图片卡片" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash风景图" */>}}
  {{</* card link="/" title="本地图片" image="/images/card-image-unprocessed.jpg" subtitle="静态目录下的原始图片。" */>}}
-  {{</* card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，由 Hugo 处理。" method="Resize" options="600x q80 webp" */>}}
+  {{</* card link="/" title="本地图片" image="images/space.jpg" subtitle="资源目录下的图片，经过Hugo处理。" method="Resize" options="600x q80 webp" */>}}
 {{</* /cards */>}}
 ```

@@ -39,37 +39,37 @@ linkTitle: 卡片

 | 参数       | 描述                                                     |
 |----------- |-----------------------------------------------------------------|
-| `link`     | URL（内部或外部）。                                     |
+| `link`     | 链接地址（内部或外部）。                                     |
 | `title`    | 卡片的标题。                                     |
-| `subtitle` | 卡片的副标题（支持 Markdown）。                           |
-| `icon`     | 图标的名称。                                             |
-| `tag`      | 标签中的文本。                                           |
-| `tagColor` | 标签的颜色：`gray`（默认）、`yellow`、`red` 和 `blue`。 |
+| `subtitle` | 卡片的副标题（支持Markdown）。                           |
+| `icon`     | 图标名称。                                               |
+| `tag`      | 标签文本。                                                    |
+| `tagColor` | 标签颜色：`gray`（默认）、`yellow`、`red` 和 `blue`。 |
  
 ## 图片卡片

-此外，卡片支持通过以下参数添加图片并进行处理：
+此外，卡片还支持通过以下参数添加图片并进行处理：

 | 参数       | 描述                                 |
-|-----------|--------------------------------------|
-| `image`   | 指定卡片的图片 URL。                 |
-| `method`  | 设置 Hugo 的图片处理方法。           |
-| `options` | 配置 Hugo 的图片处理选项。           |
+|----------- |---------------------------------------------|
+| `image`    | 指定卡片的图片URL。       |
+| `method`   | 设置Hugo的图片处理方法。        |
+| `options`  | 配置Hugo的图片处理选项。 |

 卡片支持三种类型的图片：

-1. 远程图片：`image` 参数中的完整 URL。
-2. 静态图片：使用 Hugo `static/` 目录中的相对路径。
-3. 处理后的图片：使用 Hugo `assets/` 目录中的相对路径。
+1. 远程图片：在`image`参数中填写完整的URL。
+2. 静态图片：使用Hugo的`static/`目录下的相对路径。
+3. 处理后的图片：使用Hugo的`assets/`目录下的相对路径。

-Hextra 在构建时自动检测是否需要图片处理，并应用 `options` 参数或默认设置（Resize，800x，质量 80，WebP 格式）。
-目前支持以下 `method`：`Resize`、`Fit`、`Fill` 和 `Crop`。
+Hextra在构建时会自动检测是否需要图片处理，并应用`options`参数或默认设置（Resize，800x，质量80，WebP格式）。
+目前支持的`method`有：`Resize`、`Fit`、`Fill`和`Crop`。

-有关 Hugo 内置图片处理命令、方法和选项的更多信息，请参阅其[图片处理文档](https://gohugo.io/content-management/image-processing/)。
+有关Hugo内置图片处理命令、方法和选项的更多信息，请参阅其[图片处理文档](https://gohugo.io/content-management/image-processing/)。

 ## 标签

-卡片支持添加标签，这对于显示额外的状态信息非常有用。
+卡片支持添加标签，可用于显示额外的状态信息。

 {{< cards >}}
  {{< card link="../callout" title="带默认标签的卡片" tag="标签文本" >}}
@@ -90,7 +90,7 @@ Hextra 在构建时自动检测是否需要图片处理，并应用 `options`

 ## 列数

-您可以通过将 `cols` 参数传递给 `cards` 短代码来指定卡片的最大列数。请注意，在较小的屏幕上，列仍会折叠。
+可以通过向`cards`短代码传递`cols`参数来指定卡片的最大列数。请注意，在小屏幕上列数仍会折叠。

 {{< cards cols="1" >}}
  {{< card link="/" title="顶部卡片" >}}
--- a/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md
@@ -12,7 +12,7 @@ title: 详情

 这是详情的内容。

-支持 **Markdown**。
+支持 **Markdown** 格式。

 {{% /details %}}

@@ -22,14 +22,14 @@ title: 详情

 {{% /details %}}

-## 用法
+## 使用方法

 ````markdown
 {{%/* details title="详情" */%}}

 这是详情的内容。

-支持 **Markdown**。
+支持 **Markdown** 格式。

 {{%/* /details */%}}
 ````
--- a/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md
@@ -17,7 +17,7 @@ linkTitle: 文件树
  {{< filetree/file name="hugo.toml" >}}
 {{< /filetree/container >}}

-## 用法
+## 使用方法

 ```text {filename="Markdown"}
 {{</* filetree/container */>}}
--- a/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md
@@ -1,14 +1,15 @@
 ---
 title: 图标
+next: /docs/guide/shortcodes/steps
 ---

-要在行内使用此短代码，需要在配置中启用行内短代码：
+要在行内使用此短代码，需在配置中启用行内短代码功能：

 ```yaml {filename="hugo.yaml"}
 enableInlineShortcodes: true
 ```

-可用图标的列表可以在 [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml) 中找到。
+可用图标列表可在 [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml) 中找到。

 <!--more-->

@@ -19,23 +20,23 @@ enableInlineShortcodes: true
 {{< icon "gift" >}}
 {{< icon "sparkles" >}}

-## 用法
+## 使用方法

 ```
 {{</* icon "github" */>}}
 ```

-[Heroicons](https://v1.heroicons.com/) v1 的轮廓图标默认可用。
+默认支持 [Heroicons](https://v1.heroicons.com/) v1 轮廓风格图标。

 ### 如何添加自定义图标

-创建 `data/icons.yaml` 文件，然后按照以下格式添加自定义的 SVG 图标：
+创建 `data/icons.yaml` 文件，按以下格式添加您的 SVG 图标：

 ```yaml {filename="data/icons.yaml"}
-your-icon: <svg>your icon svg content</svg>
+your-icon: <svg>您的图标 SVG 内容</svg>
 ```

-然后可以在短代码中这样使用：
+随后即可通过短代码调用：

 ```
 {{</* icon "your-icon" */>}}
@@ -43,4 +44,4 @@ your-icon: <svg>your icon svg content</svg>
 {{</* card icon="your-icon" */>}}
 ```

-提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的好地方。
+提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的优质资源平台。
--- a/exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md
@@ -6,9 +6,9 @@ sidebar:
  exclude: true
 ---

-{{< callout >}}实验性功能：通过短代码嵌入 Jupyter Notebook。请注意，并非所有单元格类型都受支持。{{< /callout >}}
+{{< callout >}}实验性功能：通过短代码嵌入 Jupyter Notebook。注意并非所有单元格类型都受支持。{{< /callout >}}

-[Jupyter Notebook](https://jupyter.org/) 是 [Project Jupyter](https://jupyter.org/) 的一个语言无关的 HTML 笔记本应用程序。它允许你创建和共享包含实时代码、方程、可视化和叙述性文本的文档。
+[Jupyter Notebook](https://jupyter.org/) 是 [Project Jupyter](https://jupyter.org/) 推出的语言无关的 HTML 笔记本应用。它允许你创建和分享包含动态代码、数学公式、可视化图表和叙述性文本的文档。

 <!--more-->

@@ -16,7 +16,7 @@ sidebar:

 ### 使用本地笔记本

-要使用 Jupyter Notebook 短代码，你需要在项目中有一个 Jupyter Notebook 文件。类似于如何[添加图片](../../organize-files#add-images)到项目中，你可以将 Jupyter Notebooks 添加到 `assets` 文件夹。
+要使用 Jupyter Notebook 短代码，你需要在项目中放置一个 Jupyter Notebook 文件。与[添加图片](../../organize-files#add-images)到项目类似，你可以将 Jupyter Notebook 放入 `assets` 文件夹。

 {{< filetree/container >}}
  {{< filetree/folder name="assets" >}}
@@ -29,7 +29,7 @@ sidebar:
  {{< /filetree/folder >}}
 {{< /filetree/container >}}

-使用 `jupyter` 短代码将 Jupyter Notebook 包含在页面中：
+使用 `jupyter` 短代码将笔记本嵌入页面：

 ```markdown {filename="content/docs/my-page.md"}
 ---
@@ -40,7 +40,7 @@ math: true
 {{%/* jupyter "notebook.ipynb" */%}}
 ```

-或者，你可以利用 Hugo 的[页面包][page-bundles]功能将 Jupyter Notebooks 与 Markdown 文件一起组织。
+或者，你可以利用 Hugo 的[页面包][page-bundles]功能，将 Jupyter Notebook 与 Markdown 文件组织在一起。

 {{< filetree/container >}}
  {{< filetree/folder name="content" >}}
@@ -64,7 +64,7 @@ math: true

 ### 使用远程笔记本

-你也可以通过提供笔记本文件的 URL 来使用远程笔记本。例如，要在页面中包含 [What is the Jupyter Notebook](https://github.com/jupyter/notebook/blob/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb) 笔记本，你可以使用以下短代码：
+你也可以通过提供笔记本文件的 URL 来使用远程笔记本。例如，要在页面中嵌入 [什么是 Jupyter Notebook](https://github.com/jupyter/notebook/blob/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb) 笔记本，可以使用以下短代码：

 ```
 {{%/* jupyter "https://raw.githubusercontent.com/jupyter/notebook/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb" */%}}
@@ -72,7 +72,7 @@ math: true

 ## 示例笔记本

-{{< callout type="info" >}}以下是包含在项目 assets 文件夹中的笔记本文件示例。{{< /callout >}}
+{{< callout type="info" >}}以下示例展示的是项目 assets 文件夹中包含的笔记本文件。{{< /callout >}}

 {{% jupyter "example.ipynb" %}}

--- a/exampleSite/content/docs/guide/shortcodes/others.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/others.zh-cn.md
@@ -3,11 +3,12 @@ title: 其他短代码
 linkTitle: 其他
 sidebar:
  exclude: true
+next: /docs/guide/deploy-site
 ---

 {{< callout emoji="ℹ️" >}}
-  其中一些是 Hugo 内置的短代码。
-  这些短代码被认为不太稳定，可能会随时更改。
+  其中部分为Hugo内置短代码。
+  这些短代码稳定性较低，可能随时变更。
 {{< /callout >}}

 ## 徽章
@@ -16,7 +17,7 @@ sidebar:
 {{</* badge "徽章" */>}}
 ```

-结果：
+效果：

 {{< badge "徽章" >}}

@@ -28,7 +29,7 @@ sidebar:
 {{</* badge content="错误" type="error" */>}}
 ```

-结果：
+效果：

 {{< badge content="信息" type="info" >}} &nbsp;
 {{< badge content="警告" type="warning" >}} &nbsp;
@@ -37,22 +38,22 @@ sidebar:
 带链接和图标：

 ```
-{{</* badge content="发布" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
+{{</* badge content="版本发布" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
 ```

-结果：
+效果：

-{{< badge content="发布" link="https://github.com/imfing/hextra/releases" icon="github" >}}
+{{< badge content="版本发布" link="https://github.com/imfing/hextra/releases" icon="github" >}}

 ## YouTube

-嵌入 YouTube 视频。
+嵌入YouTube视频。

 ```
 {{</* youtube 视频ID */>}}
 ```

-结果：
+效果：

 {{< youtube id=dQw4w9WgXcQ loading=lazy >}}

@@ -60,13 +61,13 @@ sidebar:

 ## PDF

-使用 PDF 短代码，您可以在内容中嵌入 PDF 文件。
+通过PDF短代码可在内容中嵌入PDF文件。

 ```
 {{</* pdf "https://example.com/sample.pdf" */>}}
 ```

-您也可以将 PDF 文件放在项目目录中并使用相对路径。
+也可将PDF文件置于项目目录中并使用相对路径。

 ```
 {{</* pdf "path/to/file.pdf" */>}}
--- a/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md
@@ -23,14 +23,14 @@ title: 步骤
 {{% /steps %}}


-## 用法
+## 使用方法

 {{< callout emoji="ℹ️" >}}
-  请注意，此短代码**仅适用于 Markdown 内容**。
-  如果将 HTML 内容或其他短代码作为步骤内容，可能无法按预期渲染。
+  请注意，此短代码**仅适用于Markdown内容**。
+  如果在步骤内容中放入HTML或其他短代码，可能无法按预期渲染。
 {{< /callout >}}

-在 `steps` 短代码中放置 Markdown 的 h3 标题。
+在`steps`短代码内放置Markdown的三级标题。

 ```
 {{%/* steps */%}}
--- a/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md
+++ b/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md
@@ -5,56 +5,56 @@ next: /docs/guide/deploy-site

 ## 示例

-{{< tabs items="JSON,YAML,TOML" >}}
+{{< tabs items="macOS,Linux,Windows" >}}

-{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
-{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
-{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
+  {{< tab >}}**macOS**: 苹果公司开发的桌面操作系统。{{< /tab >}}
+  {{< tab >}}**Linux**: 一款开源操作系统。{{< /tab >}}
+  {{< tab >}}**Windows**: 微软公司开发的桌面操作系统。{{< /tab >}}

 {{< /tabs >}}

-## 用法
+## 使用方法

 ### 默认

 ```
 {{</* tabs items="JSON,YAML,TOML" */>}}

-  {{</* tab */>}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
-  {{</* tab */>}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{</* /tab */>}}
-  {{</* tab */>}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{</* /tab */>}}
+  {{</* tab */>}}**JSON**: JavaScript对象表示法（JSON）是一种基于JavaScript对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
+  {{</* tab */>}}**YAML**: YAML是一种人类可读的数据序列化语言。{{</* /tab */>}}
+  {{</* tab */>}}**TOML**: TOML旨在成为一种易于阅读的最小化配置文件格式，因其明显的语义而易于理解。{{</* /tab */>}}

 {{</* /tabs */>}}
 ```

-### 指定选中索引
+### 指定默认选中项

-使用 `defaultIndex` 属性来指定选中的标签页。索引从 0 开始。
+使用 `defaultIndex` 属性指定默认选中的标签页，索引从0开始。

 ```
 {{</* tabs items="JSON,YAML,TOML" defaultIndex="1" */>}}

-  {{</* tab */>}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
-  {{</* tab */>}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{</* /tab */>}}
-  {{</* tab */>}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{</* /tab */>}}
+  {{</* tab */>}}**JSON**: JavaScript对象表示法（JSON）是一种基于JavaScript对象语法的标准文本格式，用于表示结构化数据。{{</* /tab */>}}
+  {{</* tab */>}}**YAML**: YAML是一种人类可读的数据序列化语言。{{</* /tab */>}}
+  {{</* tab */>}}**TOML**: TOML旨在成为一种易于阅读的最小化配置文件格式，因其明显的语义而易于理解。{{</* /tab */>}}

 {{</* /tabs */>}}
 ```

-默认情况下，`YAML` 标签页将被选中。
+默认会选中 `YAML` 标签页。

 {{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}

-{{< tab >}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
-{{< tab >}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{< /tab >}}
-{{< tab >}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{< /tab >}}
+{{< tab >}}**JSON**: JavaScript对象表示法（JSON）是一种基于JavaScript对象语法的标准文本格式，用于表示结构化数据。{{< /tab >}}
+{{< tab >}}**YAML**: YAML是一种人类可读的数据序列化语言。{{< /tab >}}
+{{< tab >}}**TOML**: TOML旨在成为一种易于阅读的最小化配置文件格式，因其明显的语义而易于理解。{{< /tab >}}

 {{< /tabs >}}


-### 使用 Markdown
+### 使用Markdown

-Markdown 语法，包括代码块，也受支持：
+支持包括代码块在内的Markdown语法：

 ````
 {{</* tabs items="JSON,YAML,TOML" */>}}
@@ -65,7 +65,7 @@ Markdown 语法，包括代码块，也受支持：
  ```
  {{</* /tab */>}}

-  ... 类似地添加其他标签页
+  ... 其他标签页类似添加

 {{</* /tabs */>}}
 ````
@@ -91,3 +91,35 @@ Markdown 语法，包括代码块，也受支持：
  {{< /tab >}}

 {{< /tabs >}}
+
+
+### 同步标签页
+
+具有相同 `items` 列表的标签页可以同步。启用后，选择一个标签页会更新所有具有相同 `items` 的其他标签页，并在页面间记住选择。
+
+在 `hugo.yaml` 的 `page` 部分全局启用：
+
+```yaml {filename="hugo.yaml"}
+params:
+  page:
+    tabs:
+      sync: true
+```
+
+启用后，以下两个标签页块将始终显示相同的选中项：
+
+```markdown
+{{</* tabs items="A,B" */>}}
+
+  {{</* tab */>}}A内容{{</* /tab */>}}
+  {{</* tab */>}}B内容{{</* /tab */>}}
+
+{{</* /tabs */>}}
+
+{{</* tabs items="A,B" */>}}
+
+  {{</* tab */>}}第二个A内容{{</* /tab */>}}
+  {{</* tab */>}}第二个B内容{{</* /tab */>}}
+
+{{</* /tabs */>}}
+```
--- a/exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md
+++ b/exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md
@@ -3,8 +3,7 @@ title: "语法高亮"
 weight: 3
 ---

-Hugo 使用 [Chroma](https://github.com/alecthomas/chroma)，这是一个用纯 Go 编写的通用语法高亮器，用于语法高亮。
-建议在 Markdown 内容中使用反引号来标记代码块。例如：
+Hugo 使用纯 Go 编写的通用语法高亮工具 [Chroma](https://github.com/alecthomas/chroma) 来实现代码高亮。建议在 Markdown 内容中使用反引号标记代码块，例如：

 <!--more-->

@@ -15,18 +14,18 @@ def say_hello():
 ```
 ````

-将会渲染为：
+将渲染为：

 ```python
 def say_hello():
    print("Hello!")
 ```

-## 功能
+## 功能特性

-### 文件名
+### 文件名标注

-要为代码块添加文件名或标题，请设置 `filename` 属性：
+通过设置 `filename` 属性可为代码块添加文件名或标题：

 ````markdown {filename="Markdown"}
 ```python {filename="hello.py"}
@@ -44,9 +43,7 @@ def say_hello():

 {{< new-feature version="v0.9.2" >}}

-你可以使用 `base_url` 属性提供一个基础 URL，它将与文件名结合生成一个链接。
-
-如果文件名指定了文件在基础路径中的位置，则可以包含相对路径。
+通过 `base_url` 属性可设置基础 URL，该 URL 会与文件名组合生成可点击的链接。文件名可包含相对路径以指定文件在基础路径中的位置。

 ````markdown {filename="Markdown"}
 ```go {base_url="https://github.com/imfing/hextra/blob/main/",filename="exampleSite/hugo.work"}
@@ -58,9 +55,9 @@ go 1.20
 go 1.20
 ```

-### 行号
+### 行号显示

-要设置行号，请将 `linenos` 属性设置为 `table`，并可选地设置 `linenostart` 为起始行号：
+设置 `linenos=table` 可启用行号，并通过 `linenostart` 指定起始行号：

 ````markdown {filename="Markdown"}
 ```python {linenos=table,linenostart=42}
@@ -74,9 +71,9 @@ def say_hello():
    print("Hello!")
 ```

-### 高亮行
+### 行高亮

-要高亮特定行，请将 `hl_lines` 属性设置为行号列表：
+通过 `hl_lines` 属性可高亮指定行号（支持数组格式）：

 ````markdown {filename="Markdown"}
 ```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
@@ -98,7 +95,7 @@ def main():

 ### 复制按钮

-默认情况下，代码块启用了复制按钮。可以通过修改站点配置文件来更改其行为：
+代码块默认启用复制功能，可通过站点配置文件修改其行为：

 ```yaml {linenos=table,linenostart=42,filename="hugo.yaml"}
 params:
@@ -109,6 +106,6 @@ params:
      display: hover
 ```

-## 支持的语言
+## 支持语言

-有关支持的语言列表，请参阅 [Chroma 文档](https://github.com/alecthomas/chroma#supported-languages)。
+完整支持的语言列表请参阅 [Chroma 文档](https://github.com/alecthomas/chroma#supported-languages)。