Hextra – 博客

Hextra v0.12

Fri, 20 Feb 2026 00:00:00 +0000

Hextra v0.12.0 带来了丰富的新功能，包括页面上下文菜单、图片缩放、全新设计的标签页等，同时提供全面的 WCAG 2.2 AA 无障碍改进和大量错误修复。

升级指南

对大多数站点而言没有破坏性变更。使用 Hugo Modules 更新：

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

亮点

页面上下文菜单，可复制/查看 Markdown 源码
全新设计的标签页短代码，支持单独命名和图标
Markdown 图片点击缩放
GoatCounter 分析支持
桌面端隐藏主侧边栏选项
通过 GitInfo 显示最后修改作者
禁用上一篇/下一篇导航选项
内置归档页面，按时间顺序列出博客文章
术语表短代码和布局
从 llms.txt 中排除页面/章节
移动端侧边栏排序和标签与 menu.main 对齐
通过 CSS 变量覆盖支持稳定的内容宽度
全面的 WCAG 2.2 AA 无障碍改进

新功能

页面上下文菜单

页面上下文菜单提供下拉按钮，可将页面内容复制为 Markdown 或查看原始 Markdown 源码。随着越来越多用户将文档输入生成式 AI 工具，快速获取干净的 Markdown 变得越来越有用。通过模板变量（{url}、{title}、{markdown_url}）添加自定义链接，可以在菜单中直接集成“询问 AI”快捷方式或其他功能。

要使用“以 Markdown 查看”和 {markdown_url} 功能，请在站点配置中启用 Markdown 输出格式：

hugo.yaml

outputs:
 page: [html, markdown]
 section: [html, rss, markdown]

然后配置页面上下文菜单：

hugo.yaml

params:
 page:
 contextMenu:
 enable: true
 links:
 - name: "Ask AI"
 url: "https://example.com?content={markdown_url}"
 icon: "sparkles"

标签页重设计与图标支持

标签页短代码经过重新设计。现在可以直接在每个 tab 短代码上设置标签名称，可选的 icon 参数可在标签文字前显示图标。之前的语法仍然支持。

{{< tabs >}}
 {{< tab name="Photos" icon="photograph" >}}管理和整理您的照片库。{{< /tab >}}
 {{< tab name="Music" icon="music-note" >}}浏览和播放您喜爱的曲目。{{< /tab >}}
 {{< tab name="Videos" icon="film" >}}观看和串流视频内容。{{< /tab >}}
{{< /tabs >}}

图片缩放

通过新的配置选项，启用 Markdown 图片的点击缩放功能，基于 medium-zoom 实现。

hugo.yaml

params:
 imageZoom:
 enable: true

GoatCounter 分析

在现有的 Google Analytics、Umami 和 Matomo 集成之外，新增 GoatCounter 分析的内置支持。

隐藏主侧边栏

新的 Front Matter 参数允许在桌面端隐藏主侧边栏，使内容页面获得全宽显示。

content/my-page.md

---
title: My Page
sidebar:
 hide: true
---

最后修改作者

使用 Hugo 的 GitInfo 功能，在"最后更新"日期旁显示最后提交的作者。

hugo.yaml

params:
 displayUpdatedAuthor: true

hugo.yaml

params:
 page:
 displayPagination: false

LLMs.txt 排除

通过在 Front Matter 中设置 llms: false，将单个页面或整个章节从 llms.txt 输出中排除。

content/private-page.md

---
title: "Private Page"
llms: false
---

归档页面

新的内置 archives 布局按年份分组，以时间线形式展示博客文章，每篇文章标题后内联显示标签。

content/archives/_index.md

---
title: Archives
layout: archives
---

术语表

站点级术语表，提供专用列表页面和用于内联定义的 term 短代码。

无障碍

全面的 WCAG 2.2 AA 无障碍改进 (#924)：

所有页面添加跳转到内容链接和 ARIA 地标角色
所有交互组件（主题切换、标签页、侧边栏、文件树、下拉菜单、搜索、菜单）添加 ARIA 属性
标签页和主题切换的键盘导航（方向键、Enter、Escape）
支持 prefers-reduced-motion 和全局 focus-visible 样式
15 个新的 i18n 无障碍键，在全部 21 个语言环境中提供完整翻译
将所有硬编码的英文 aria-label 字符串替换为 i18n 查找

使用体验优化

改进表格可读性样式
标题支持 Markdown 属性
多语言章节着陆页的活动链接检测改进
卡片短代码支持可选的图片 alt 参数
OpenGraph 元数据支持页面资源包图片
内容宽度默认保持一致，支持通过 CSS 变量覆盖自定义布局

修复

修复 render-link 中 relref 基础前缀重复问题
修复嵌套在步骤中的标签页渲染
移动端侧边栏排序和标签与 menu.main 对齐
侧边栏中遵循 search.enable 设置
移动端下拉菜单中遵循 toc 页面参数
增强 FlexSearch 匹配高亮和安全的 DOM 操作
修复卡片副标题定位
处理子路径部署中 OG 图片路径的前导斜杠
修复 FlexSearch 返回结果页数少于预期的问题
将 Umami 分析的默认文件改为 script.js
修复 Hugo v0.156.0+ 的 RSS 作者查找 (.Site.Params.Author)

文档与 i18n

添加意大利语本地化
链接 KaTeX 文档
将 details 短代码文档更新为尖括号语法

贡献者

此版本由 11 位新贡献者共同参与完成：

@ghac101 - Umami 分析修复、禁用上一篇/下一篇导航
@pmarrapese - 标题 Markdown 属性支持
@Bubbler-4 - details 短代码文档
@bloovis - FlexSearch 结果计数修复
@AntoninPvr - 卡片副标题定位修复
@illia-v - 移动端目录和搜索切换修复
@gallochri - 意大利语本地化
@MatheusFlausino - LLMs.txt 排除
@daniseijo - 最后修改作者功能
@confusedkernel - 归档页面
@Fenyutanchan - Hugo v0.156.0 RSS 作者兼容性修复

同时感谢回归贡献者 @KStocky、@ldez、@kowyo、@torbjornbp、@yuri1969 和 @PrintN 的持续贡献。

完整变更日志: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0

Hextra v0.11

Sat, 30 Aug 2025 00:00:00 +0000

Hextra v0.11.0 专注于打磨使用体验并带来数个实用新组件：站点级顶部横幅、改进的提示框与徽章、更丰富的卡片、分析工具集成，以及多项导航优化。同时包含稳定性修复和文档更新。

升级指南

对大多数站点而言没有破坏性变更。使用 Hugo Modules 更新：

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

亮点

用于公告的顶栏横幅组件
重新设计的提示框，样式更清晰
支持 Umami 与 Matomo 分析
Asciinema 短代码用于终端录屏
外链装饰选项
单页（非文档、非博客）支持面包屑
导航栏增强：图标链接项与更优布局
徽章与卡片的自定义能力提升
主题切换增加「System」选项

新功能

顶部横幅

为公告、发布或状态消息添加一个站点级、可关闭的横幅。

hugo.yaml

params:
 banner:
 key: "announcement"
 message: Welcome!

提示框重设计

Callout 获得样式刷新，在各主题下具备更好的可读性与强调效果。

分析：Umami 与 Matomo

内置以下分析平台的配置支持：

Umami
Matomo

Asciinema 短代码

使用全新的 Asciinema 短代码嵌入 Asciinema 终端录屏。

{{< asciinema id="123456" autoplay=true loop=true >}}

导航栏增强

支持在导航栏链接项中使用图标
优化菜单的相对位置，使其与语言切换器等项协同更佳

值得一提的是，版本 0.10.2 已支持在导航栏添加语言切换器与主题切换。

外链装饰

可选地为外部链接添加轻量的外链标识装饰。

hugo.yaml

params:
 externalLinkDecoration: true

启用面包屑

在单页（非文档、非博客）上，通过在 Front Matter 中设置 breadcrumbs: true 启用面包屑。

content/about.md

---
title: About
breadcrumbs: true
---

卡片与徽章的改进

卡片：新增 tagIcon 与 tagBorder 选项。
徽章：新增颜色与边框样式。

使用体验优化

主题切换：增加「System」选项
字体排版：改进带复选框的任务列表样式
语言切换器：与图标菜单项的排序更合理

修复

Giscus：正确同步主题与语言
卡片：修复 RTL 场景下的徽章渲染
导航栏：优化菜单位置与交互

文档与 i18n

文档：新增页面介绍 Hextra 的短代码
i18n：为 zh-cn 增加 copyCode 与 system 翻译

完整变更日志: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

Hextra v0.10.0 是一个重大版本更新，包含多项新功能、架构升级和使用体验优化。

本次更新还包含了来自 10 位新贡献者的代码提交，并解决了社区长期期待的功能需求。

升级指南

Important

破坏性变更：此版本包含多项不兼容改动。升级前请仔细阅读检查清单和迁移指南。

升级至 v0.10.0 前，请确保：

已安装 Hugo v0.146.0+（扩展版）
检查自定义 CSS 的类名变更（参见 CSS 类前缀变更和 Tailwind CSS v4）
确认构建环境可访问互联网以下载 LaTeX 和/或 Mermaid 资源

准备就绪后，更新 Hugo 模块：

hugo mod get -u github.com/imfing/hextra@v0.10.0

新功能

以下是本版本值得关注的新特性：

导航栏下拉菜单支持：创建层级导航菜单
增强搜索体验：改进全标题搜索精度
llms.txt 支持：生成 AI 友好的站点大纲
目录滚动高亮：滚动时自动高亮当前章节
同步标签页切换：跨多组标签页同步选择状态
博客列表分页：为博客列表添加分页控件
MathJax 支持：在 KaTeX 外新增数学公式渲染引擎

导航栏下拉菜单支持

在导航栏中创建下拉菜单，优化导航项组织方式。

hugo.yaml

menu:
 main:
 - identifier: products
 name: "产品"
 - name: "产品A"
 parent: products
 url: "/product-a"
 - name: "产品B"
 parent: products
 url: "/product-b"

增强搜索体验

全标题搜索：可搜索所有层级标题内容，不限于页面标题
提升结果精度：改进标题处理和链接准确性
修复结果导航：搜索结果现在能正确跳转到对应章节

特别感谢 @ldez 推动搜索功能升级！

llms.txt 支持

现支持生成 llms.txt 格式输出，使站点内容更便于 AI 工具和语言模型获取上下文参考。

hugo.yaml

outputs:
 home: [html, llms]

这将在站点根目录生成 llms.txt 文件。

目录滚动高亮

滚动页面时，目录会自动高亮当前章节，使导航更加直观。

同步标签页切换

相同内容的标签页现在支持跨组同步。启用同步后，选择某个标签会更新所有包含相同项目的标签组（且会记住选择状态）。

hugo.yaml

params:
 page:
 tabs:
 sync: true

博客列表分页

为博客列表页面添加基础分页控件。

hugo.yaml

params:
 blog:
 list:
 pagerSize: 20 # 每页文章数

MathJax 支持

除默认的 KaTeX 外，新增 MathJax 数学公式渲染引擎支持，可按需选择。

hugo.yaml

params:
 math:
 engine: "mathjax" # 默认为 "katex"

技术改进

框架与构建系统

Tailwind CSS v4 迁移：完整迁移至 Tailwind CSS v4，提供更好的定制支持
Hugo 模板系统：适配 Hugo 新版模板系统（v0.146.0+）以确保未来兼容性
数学公式服务端渲染：默认使用 Hugo 原生渲染改进数学公式处理
FlexSearch 0.8 升级：搜索引擎升级至 FlexSearch 0.8，提升 CJK（中日韩）内容编码处理能力
增强资源管理：KaTeX 和 Mermaid 资源支持从 CDN 或本地加载

使用体验优化

动态 favicon 切换：根据色彩偏好自动更新网站图标
反向分页：支持通过页面 front matter 设置 reversePagination
Google 索引控制：新增页面参数控制是否允许 Google 索引
宽度处理改进：通过 CSS 变量优化响应式设计控制
样式改进：现代化 Markdown 表格和水平线样式

错误修复与稳定性

Giscus 主题同步：评论模块现在正确跟随暗黑/明亮模式切换
搜索结果准确性：修复搜索结果链接和标题转义问题
标签页切换：解决非同步模式下的导航问题
幽灵滚动：修复禁用页脚时出现的异常滚动行为
图片可访问性：避免重复渲染 alt 文本
链接渲染：改进复杂站点结构下的基础 URL 处理

迁移指南

Hugo 版本要求：需 Hugo v0.146.0+（扩展版）
CSS 类前缀变更：组件 CSS 类现统一使用 hextra- 前缀
资源管理：KaTeX 和 Mermaid 资源改为构建时下载
Tailwind CSS v4：内部 CSS 编译现使用 Tailwind CSS v4.x 并采用 hx: 前缀

Hugo 版本要求

影响：使用旧版 Hugo 的站点

Hextra v0.10.0 因采用新模板系统，要求 Hugo v0.146.0 或更高版本（扩展版）。

需执行操作：升级 Hextra 前先更新 Hugo 至 v0.146.0+

CSS 类前缀变更

影响：自定义 CSS 中引用了 Hextra 组件类的站点

v0.10.0 为大多数组件 CSS 类引入统一的 hextra- 前缀，以提高可维护性并避免与用户样式冲突。

需执行操作：如果自定义 CSS 中引用了 Hextra 组件，请更新以下类名：

区域	旧类名	新类名
搜索（容器）	`.search-wrapper`	`.hextra-search-wrapper`
搜索（输入框）	`.search-input`	`.hextra-search-input`
搜索（结果）	`.search-results`	`.hextra-search-results`
搜索（标题）	`.search-wrapper .title`	`.hextra-search-wrapper .hextra-search-title`
搜索（活动项）	`.search-wrapper .active`	`.hextra-search-wrapper .hextra-search-active`
搜索（无结果）	`.search-wrapper .no-result`	`.hextra-search-wrapper .hextra-search-no-result`
搜索（前缀）	`.search-wrapper .prefix`	`.hextra-search-wrapper .hextra-search-prefix`
搜索（摘要）	`.search-wrapper .excerpt`	`.hextra-search-wrapper .hextra-search-excerpt`
搜索（匹配项）	`.search-wrapper .match`	`.hextra-search-wrapper .hextra-search-match`
导航栏模糊效果	`.nav-container-blur`	`.hextra-nav-container-blur`
汉堡菜单	`.hamburger-menu`	`.hextra-hamburger-menu`
主题切换	`.theme-toggle`	`.hextra-theme-toggle`
语言切换器	`.language-switcher`	`.hextra-language-switcher`
侧边栏容器	`.sidebar-container`	`.hextra-sidebar-container`
侧边栏活动项	`.sidebar-active-item`	`.hextra-sidebar-active-item`
代码文件名	`.filename`	`.hextra-code-filename`
复制图标	`.copy-icon`	`.hextra-copy-icon`
成功图标	`.success-icon`	`.hextra-success-icon`
步骤组件	`.steps`	`.hextra-steps`

KaTeX 和 Mermaid 资源管理

影响：使用 KaTeX 或 Mermaid 的站点

v0.10.0 改为在构建时从 CDN 下载 KaTeX 和 Mermaid 资源。

变更内容：

构建过程需要联网下载这些资源
构建后不再需要外部 CDN 调用

需执行操作：

确保构建环境可访问互联网以下载资源
隔离环境中的站点需预下载资源并配置 Hextra 加载路径

Tailwind CSS v4

影响：大量自定义 CSS 引用了 hx-* 类名的站点

虽然 Hextra 内部已处理 Tailwind CSS v4 迁移，但深度定制的站点可能需要额外调整。

变更内容：

内部 CSS 编译使用 Tailwind CSS v4.x
工具类前缀改为 hx: 而非 hx-

贡献者

本次发布得益于 10 位新贡献者的代码提交：

@oosquare - KaTeX 字体、图片渲染钩子、链接处理改进
@Zabriskije - 修复幽灵滚动问题
@miniwater - 自定义页脚居中、图片 alt 文本优化
@MattDodsonEnglish - Google 索引控制、OpenGraph 文档
@KStocky - 反向分页功能
@PrintN - 文档展示增强
@hobobandy - 标题间距优化
@dlwocks31 - 韩语翻译更新
@TwoAnts - 修复 Giscus 主题切换
@ldez - 搜索功能改进与错误修复

同时感谢长期贡献者 @deining 和 @yuri1969 在文档、翻译和技术改进方面的持续支持。

完整更新日志：https://github.com/imfing/hextra/compare/v0.9.7…v0.10.0

Markdown 语法指南

Wed, 01 Jan 2020 00:00:00 +0000

本文展示了 Hugo 内容文件中可用的基础 Markdown 语法示例。

基础语法

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

二级标题

三级标题

四级标题

五级标题

六级标题

强调

*这段文字会显示为斜体*
_这段文字也会显示为斜体_

**这段文字会显示为粗体**
__这段文字也会显示为粗体__

_你可以**组合**使用_

这段文字会显示为斜体

这段文字也会显示为斜体

这段文字会显示为粗体

这段文字也会显示为粗体

你可以组合使用

列表

无序列表

* 项目1
* 项目2
* 子项目2a
* 子项目2b

项目1
项目2
- 子项目2a
- 子项目2b

有序列表

1. 项目1
2. 项目2
3. 项目3
1. 子项目3a
2. 子项目3b

图片

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

链接

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

Hugo

引用块

正如牛顿所说：

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

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

行内代码

行内`代码`会用`反引号包裹`起来。

行内代码会用反引号包裹起来。

代码块

语法高亮

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

表格

| 语法 | 描述 |
| --------- | ----------- |
| 标题 | 标题文本 |
| 段落 | 正文内容 |

语法	描述
标题	标题文本
段落	正文内容

Hextra – 博客

Hextra v0.12

升级指南

亮点

新功能

页面上下文菜单

标签页重设计与图标支持

图片缩放

GoatCounter 分析

隐藏主侧边栏

最后修改作者

禁用上一篇/下一篇导航

LLMs.txt 排除

归档页面

术语表

无障碍

使用体验优化

修复

文档与 i18n

贡献者

Hextra v0.11

升级指南

亮点

新功能

顶部横幅

提示框重设计

分析：Umami 与 Matomo

Asciinema 短代码

导航栏增强

外链装饰

启用面包屑

卡片与徽章的改进

使用体验优化

修复

文档与 i18n

Hextra v0.10

升级指南

新功能

导航栏下拉菜单支持

增强搜索体验

llms.txt 支持

目录滚动高亮

同步标签页切换

博客列表分页

MathJax 支持

技术改进

框架与构建系统

使用体验优化

错误修复与稳定性

迁移指南

Hugo 版本要求

CSS 类前缀变更

KaTeX 和 Mermaid 资源管理

Tailwind CSS v4

贡献者

Markdown 语法指南

基础语法

标题

二级标题

三级标题

四级标题

五级标题

六级标题

强调

列表

无序列表

有序列表

图片

链接

引用块

行内代码

代码块

语法高亮

表格

参考资料