diff --git a/exampleSite/content/about/index.zh-cn.md b/exampleSite/content/about/index.zh-cn.md index 196fbce..d84cc2e 100644 --- a/exampleSite/content/about/index.zh-cn.md +++ b/exampleSite/content/about/index.zh-cn.md @@ -3,18 +3,18 @@ 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/) - [Heroicons](https://heroicons.com/) - [Nextra](https://nextra.vercel.app/) -- [Next.js](https://nextjs.org/) +- [Next.js](https://nextjs.org/) \ No newline at end of file diff --git a/exampleSite/content/blog/_index.zh-cn.md b/exampleSite/content/blog/_index.zh-cn.md index 3389c28..4270b82 100644 --- a/exampleSite/content/blog/_index.zh-cn.md +++ b/exampleSite/content/blog/_index.zh-cn.md @@ -7,4 +7,4 @@ title: "博客" RSS 订阅 {{< icon name="rss" attributes="height=14" >}} {{< /hextra/hero-badge >}} - + \ No newline at end of file diff --git a/exampleSite/content/blog/markdown.zh-cn.md b/exampleSite/content/blog/markdown.zh-cn.md index 9eeba01..ef1f5ea 100644 --- 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 语法示例。 ## 基础语法 @@ -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/) -- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown) +- [Markdown 语法](https://www.markdownguide.org/basic-syntax/) +- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown) \ No newline at end of file diff --git a/exampleSite/content/blog/v0.10.md b/exampleSite/content/blog/v010.md similarity index 100% rename from exampleSite/content/blog/v0.10.md rename to exampleSite/content/blog/v010.md diff --git a/exampleSite/content/blog/v010.zh-cn.md b/exampleSite/content/blog/v010.zh-cn.md new file mode 100644 index 0000000..44d8f32 --- /dev/null +++ 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 是一个重大版本更新，包含了新功能、架构升级和体验优化。 + + + +本次更新还包含了来自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 \ No newline at end of file diff --git a/exampleSite/content/docs/_index.zh-cn.md b/exampleSite/content/docs/_index.zh-cn.md index 9f988fc..213441a 100644 --- a/exampleSite/content/docs/_index.zh-cn.md +++ b/exampleSite/content/docs/_index.zh-cn.md @@ -1,40 +1,40 @@ --- linkTitle: "文档" -title: 介绍 +title: 简介 --- -👋 你好！欢迎来到 Hextra 文档！ +👋 你好！欢迎来到 Hextra 文档中心！ ## 什么是 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/ [flex-search]: https://github.com/nextapps-de/flexsearch -[tailwind-css]: https://tailwindcss.com/ +[tailwind-css]: https://tailwindcss.com/ \ No newline at end of file diff --git a/exampleSite/content/docs/advanced/_index.zh-cn.md b/exampleSite/content/docs/advanced/_index.zh-cn.md index b53616e..d16e875 100644 --- 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 --- -本节涵盖了一些主题的高级内容。 +本节涵盖该主题的一些高级内容。 {{< 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 >}} \ No newline at end of file diff --git a/exampleSite/content/docs/advanced/comments.zh-cn.md b/exampleSite/content/docs/advanced/comments.zh-cn.md index 0622483..8ed44bd 100644 --- 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 中为特定页面启用或禁用评论： diff --git a/exampleSite/content/docs/advanced/customization.zh-cn.md b/exampleSite/content/docs/advanced/customization.zh-cn.md index 94ebf21..2299816 100644 --- 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` 配置文件中提供了一些默认的自定义选项来配置主题。 +本页描述了可用选项以及如何进一步自定义主题。 ## 自定义 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/ \ No newline at end of file diff --git a/exampleSite/content/docs/advanced/multi-language.zh-cn.md b/exampleSite/content/docs/advanced/multi-language.zh-cn.md index f5325a8..b1f372a 100644 --- 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 -## 启用多语言 +## 启用多语言功能 -要使我们的网站支持多语言，我们需要告诉 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/) diff --git a/exampleSite/content/docs/getting-started.zh-cn.md b/exampleSite/content/docs/getting-started.zh-cn.md index aac0ab4..c738928 100644 --- 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" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template) -您可以通过使用上述模板仓库快速入门。 +您可以通过使用上述模板仓库快速开始。 -我们提供了一个 [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 %}} diff --git a/exampleSite/content/docs/guide/_index.zh-cn.md b/exampleSite/content/docs/guide/_index.zh-cn.md index 02a7a0b..49c1a3d 100644 --- 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： diff --git a/exampleSite/content/docs/guide/configuration.zh-cn.md b/exampleSite/content/docs/guide/configuration.zh-cn.md index a008da0..0796b91 100644 --- 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) 以全面了解可用设置和最佳实践。 @@ -13,7 +15,7 @@ Hugo 从您 Hugo 站点根目录下的 `hugo.yaml` 文件中读取配置。 ### 菜单 -右上角的菜单在配置文件的 `menu.main` 部分中定义： +右上角菜单在配置文件的 `menu.main` 部分定义： ```yaml {filename="hugo.yaml"} menu: @@ -38,37 +40,58 @@ menu: icon: github ``` -有不同类型的菜单项： +菜单项有以下几种类型： -1. 使用 `pageRef` 链接到站点内的页面 - ```yaml - - name: 文档 - pageRef: /docs - ``` -2. 使用 `url` 链接到外部 URL - ```yaml - - name: GitHub - url: "https://github.com" - ``` -3. 使用 `type: search` 的搜索栏 - ```yaml - - name: 搜索 - params: - type: search - ``` +1. 通过 `pageRef` 链接到站内页面 + ```yaml + - name: 文档 + pageRef: /docs + ``` +2. 通过 `url` 链接到外部网址 + ```yaml + - name: GitHub + url: "https://github.com" + ``` +3. 搜索栏，使用 `type: search` + ```yaml + - name: 搜索 + params: + type: search + ``` 4. 图标 - ```yaml - - name: GitHub - params: - icon: github - ``` + ```yaml + - name: GitHub + params: + 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,35 +308,36 @@ 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 + # full | forward | reverse | strict tokenize: forward ``` [`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" ``` \ No newline at end of file diff --git a/exampleSite/content/docs/guide/deploy-site.zh-cn.md b/exampleSite/content/docs/guide/deploy-site.zh-cn.md index f03d4db..9f09afa 100644 --- 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 站点的指南。 ## 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://.github.io//`。 +默认配置中，GitHub Actions 工作流 `.github/workflows/pages.yaml` 假设站点部署在 `https://<用户名>.github.io/<仓库名>/`。 -如果您部署到 `https://.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` | +| 配置项 | 值 | +| ---------------- | -------------------- | +| 生产分支 | `main` | +| 构建命令 | `hugo --gc --minify` | +| 构建输出目录 | `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) \ No newline at end of file diff --git a/exampleSite/content/docs/guide/diagrams.zh-cn.md b/exampleSite/content/docs/guide/diagrams.zh-cn.md index 6904ffa..0e03f43 100644 --- 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) 绘制图表。 ## 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: 理性思考
占据上风！ - John-->>Alice: 很好！ + John-->>Alice: 好极了！ John->>Bob: 你怎么样？ Bob-->>John: 非常好！ ``` -更多信息，请参考 [Mermaid 文档](https://mermaid-js.github.io/mermaid/#/)。 \ No newline at end of file +更多信息请参阅 [Mermaid 官方文档](https://mermaid-js.github.io/mermaid/#/)。 \ No newline at end of file diff --git a/exampleSite/content/docs/guide/latex.zh-cn.md b/exampleSite/content/docs/guide/latex.zh-cn.md index 057ccc9..b59c46f 100644 --- 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/ \ No newline at end of file diff --git a/exampleSite/content/docs/guide/markdown.zh-cn.md b/exampleSite/content/docs/guide/markdown.zh-cn.md index 9981e35..54f578d 100644 --- 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 语法示例。 @@ -11,28 +11,28 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来 ### 文本样式 -| 样式 | 语法 | 示例 | 输出 | -| -------- | -------- | ------ | ------ | -| 粗体 | `**粗体文本**` | `**粗体文本**` | **粗体文本** | -| 斜体 | `*斜体文本*` | `*斜体文本*` | *斜体文本* | -| 删除线 | `~~删除线文本~~` | `~~删除线文本~~` | ~~删除线文本~~ | -| 下标 | `` | `这是一个下标文本` | 这是一个下标文本 | -| 上标 | `` | `这是一个上标文本` | 这是一个上标文本 | +| 样式 | 语法 | 示例 | 输出 | +| :----- | :--------------- | :------------------------ | :---------------------- | +| 粗体 | `**粗体文本**` | `**粗体文本**` | **粗体文本** | +| 斜体 | `*斜体文本*` | `*斜体文本*` | _斜体文本_ | +| 删除线 | `~~删除线文本~~` | `~~删除线文本~~` | ~~删除线文本~~ | +| 下标 | `` | `这是下标文本` | 这是下标文本 | +| 上标 | `` | `这是上标文本` | 这是上标文本 | ### 引用块 -带出处的引用块 +带出处的引用 > 不要通过共享内存来通信，而要通过通信来共享内存。
> — Rob Pike[^1] -[^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} > 不要通过共享内存来通信，而要通过通信来共享内存。
> — Rob Pike[^1] -[^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/) \ No newline at end of file +- [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/) diff --git a/exampleSite/content/docs/guide/organize-files.zh-cn.md b/exampleSite/content/docs/guide/organize-files.zh-cn.md index 3a1a6fb..14c2081 100644 --- 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` | 其他所有目录 | 单页文章视图，无侧边栏。 | +| 布局 | 目录 | 特点 | +| :-------- | :----------------- | :------------------------------------------------------------- | +| `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) diff --git a/exampleSite/content/docs/guide/shortcodes/_index.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/_index.zh-cn.md index cd1341f..fd549d2 100644 --- 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" >}} diff --git a/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md index ccd0444..af1b52d 100644 --- 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 > [!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 {{}} - Hugo 可用于创建各种类型的网站，包括博客、作品集、文档站点等。 + Hugo可用于创建各种类型的网站，包括博客、作品集、文档站点等。 {{}} ``` -### 信息 +### 信息提示 {{< callout type="info" >}} - 请访问 GitHub 查看最新版本。 + 请访问GitHub查看最新发布版本。 {{< /callout >}} ```markdown {{}} - 请访问 GitHub 查看最新版本。 + 请访问GitHub查看最新发布版本。 {{}} ``` -### 警告 +### 警告提示 {{< callout type="warning" >}} - 此 API 将在下一个版本中弃用。 + 此API将在下一版本中弃用。 {{< /callout >}} ```markdown {{}} - **提示框** 是一段简短的文本，旨在吸引注意力。 + 此API将在下一版本中弃用。 {{}} ``` -### 错误 +### 错误提示 {{< callout type="error" >}} - 出错了，系统即将崩溃。 + 出现错误，系统即将崩溃。 {{< /callout >}} ```markdown {{}} - 出错了，系统即将崩溃。 + 出现错误，系统即将崩溃。 {{}} ``` \ No newline at end of file diff --git a/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md index 38a44a9..f183d73 100644 --- 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 >}} -## 用法 +## 使用方法 ``` {{}} @@ -29,9 +29,9 @@ linkTitle: 卡片 ``` {{}} - {{}} + {{}} {{}} - {{}} + {{}} {{}} ``` @@ -39,37 +39,37 @@ linkTitle: 卡片 | 参数 | 描述 | |----------- |-----------------------------------------------------------------| -| `link` | URL（内部或外部）。 | -| `title` | 卡片的标题。 | -| `subtitle` | 卡片的副标题（支持 Markdown）。 | -| `icon` | 图标的名称。 | -| `tag` | 标签中的文本。 | -| `tagColor` | 标签的颜色：`gray`（默认）、`yellow`、`red` 和 `blue`。 | +| `link` | 链接地址（内部或外部）。 | +| `title` | 卡片的标题。 | +| `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="顶部卡片" >}} diff --git a/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/details.zh-cn.md index 6a4697c..cf592ac 100644 --- 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 */%}} ```` diff --git a/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md index d67c7d1..a8b3522 100644 --- 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"} {{}} diff --git a/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md index e11e7f5..2ac6b70 100644 --- 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) 中找到。 @@ -19,23 +20,23 @@ enableInlineShortcodes: true {{< icon "gift" >}} {{< icon "sparkles" >}} -## 用法 +## 使用方法 ``` {{}} ``` -[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: your icon svg content +your-icon: 您的图标 SVG 内容 ``` -然后可以在短代码中这样使用： +随后即可通过短代码调用： ``` {{}} @@ -43,4 +44,4 @@ your-icon: your icon svg content {{}} ``` -提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的好地方。 \ No newline at end of file +提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的优质资源平台。 \ No newline at end of file diff --git a/exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/jupyter.zh-cn.md index 6aa5686..1cf4b4b 100644 --- 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 笔记本应用。它允许你创建和分享包含动态代码、数学公式、可视化图表和叙述性文本的文档。 @@ -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" %}} diff --git a/exampleSite/content/docs/guide/shortcodes/others.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/others.zh-cn.md index 6e35936..0ff3a5a 100644 --- 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 "徽章" >}} @@ -28,7 +29,7 @@ sidebar: {{}} ``` -结果： +效果： {{< badge content="信息" type="info" >}}   {{< badge content="警告" type="warning" >}}   @@ -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" >}} ## YouTube -嵌入 YouTube 视频。 +嵌入YouTube视频。 ``` {{}} ``` -结果： +效果： {{< youtube id=dQw4w9WgXcQ loading=lazy >}} @@ -60,13 +61,13 @@ sidebar: ## PDF -使用 PDF 短代码，您可以在内容中嵌入 PDF 文件。 +通过PDF短代码可在内容中嵌入PDF文件。 ``` {{}} ``` -您也可以将 PDF 文件放在项目目录中并使用相对路径。 +也可将PDF文件置于项目目录中并使用相对路径。 ``` {{}} diff --git a/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/steps.zh-cn.md index 07b3b3e..df67693 100644 --- 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 */%}} diff --git a/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md b/exampleSite/content/docs/guide/shortcodes/tabs.zh-cn.md index e177caa..9676cac 100644 --- 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 >}} -## 用法 +## 使用方法 ### 默认 ``` {{}} - {{}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{}} - {{}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{}} - {{}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{}} + {{}}**JSON**: JavaScript对象表示法（JSON）是一种基于JavaScript对象语法的标准文本格式，用于表示结构化数据。{{}} + {{}}**YAML**: YAML是一种人类可读的数据序列化语言。{{}} + {{}}**TOML**: TOML旨在成为一种易于阅读的最小化配置文件格式，因其明显的语义而易于理解。{{}} {{}} ``` -### 指定选中索引 +### 指定默认选中项 -使用 `defaultIndex` 属性来指定选中的标签页。索引从 0 开始。 +使用 `defaultIndex` 属性指定默认选中的标签页，索引从0开始。 ``` {{}} - {{}}**JSON**: JavaScript 对象表示法（JSON）是一种基于 JavaScript 对象语法的标准文本格式，用于表示结构化数据。{{}} - {{}}**YAML**: YAML 是一种人类可读的数据序列化语言。{{}} - {{}}**TOML**: TOML 旨在成为一种最小化的配置文件格式，由于其明显的语义，易于阅读。{{}} + {{}}**JSON**: JavaScript对象表示法（JSON）是一种基于JavaScript对象语法的标准文本格式，用于表示结构化数据。{{}} + {{}}**YAML**: YAML是一种人类可读的数据序列化语言。{{}} + {{}}**TOML**: TOML旨在成为一种易于阅读的最小化配置文件格式，因其明显的语义而易于理解。{{}} {{}} ``` -默认情况下，`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语法： ```` {{}} @@ -65,7 +65,7 @@ Markdown 语法，包括代码块，也受支持： ``` {{}} - ... 类似地添加其他标签页 + ... 其他标签页类似添加 {{}} ```` @@ -90,4 +90,36 @@ Markdown 语法，包括代码块，也受支持： ``` {{< /tab >}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} + + +### 同步标签页 + +具有相同 `items` 列表的标签页可以同步。启用后，选择一个标签页会更新所有具有相同 `items` 的其他标签页，并在页面间记住选择。 + +在 `hugo.yaml` 的 `page` 部分全局启用： + +```yaml {filename="hugo.yaml"} +params: + page: + tabs: + sync: true +``` + +启用后，以下两个标签页块将始终显示相同的选中项： + +```markdown +{{}} + + {{}}A内容{{}} + {{}}B内容{{}} + +{{}} + +{{}} + + {{}}第二个A内容{{}} + {{}}第二个B内容{{}} + +{{}} +``` \ No newline at end of file diff --git a/exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md b/exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md index 6e51532..a51e406 100644 --- 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 内容中使用反引号标记代码块，例如： @@ -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)。 \ No newline at end of file +完整支持的语言列表请参阅 [Chroma 文档](https://github.com/alecthomas/chroma#supported-languages)。 \ No newline at end of file