---
title: "Hextra v0.12"
date: 2026-02-20
authors:
  - name: imfing
    link: https://github.com/imfing
    image: https://github.com/imfing.png
tags:
  - Release
---

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

<!--more-->

## 升级指南

对大多数站点而言没有破坏性变更。使用 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) 更新：

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

## 亮点

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

## 新功能

### 页面上下文菜单

![页面上下文菜单](https://github.com/user-attachments/assets/0b55bee9-6f4d-4e1d-9461-60c40208cb6c)

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

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

```yaml {filename="hugo.yaml"}
outputs:
  page: [html, markdown]
  section: [html, rss, markdown]
```

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

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

### 标签页重设计与图标支持

[标签页短代码]({{% relref "docs/guide/shortcodes/tabs" %}})经过重新设计。现在可以直接在每个 `tab` 短代码上设置标签名称，可选的 `icon` 参数可在标签文字前显示图标。之前的语法仍然支持。

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

![带图标的标签页](https://github.com/user-attachments/assets/afa4cb8f-615c-4f01-8ae4-81a64c9ce391)

### 图片缩放

通过新的配置选项，启用 Markdown 图片的点击缩放功能，基于 [medium-zoom](https://github.com/francoischalifour/medium-zoom) 实现。

```yaml {filename="hugo.yaml"}
params:
  imageZoom:
    enable: true
```

### GoatCounter 分析

在现有的 Google Analytics、Umami 和 Matomo 集成之外，新增 [GoatCounter](https://www.goatcounter.com/) 分析的内置支持。

### 隐藏主侧边栏

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

```yaml {filename="content/my-page.md"}
---
title: My Page
sidebar:
  hide: true
---
```

### 最后修改作者

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

```yaml {filename="hugo.yaml"}
params:
  displayUpdatedAuthor: true
```

![最后修改作者](https://github.com/user-attachments/assets/275b7177-e089-483c-abb6-6d8f16616b9b)

### 禁用上一篇/下一篇导航

在站点范围内禁用上一篇/下一篇导航按钮：

```yaml {filename="hugo.yaml"}
params:
  page:
    displayPagination: false
```

### LLMs.txt 排除

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

```yaml {filename="content/private-page.md"}
---
title: "Private Page"
llms: false
---
```

### 归档页面

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

```yaml {filename="content/archives/_index.md"}
---
title: Archives
layout: archives
---
```

![归档页面](https://github.com/user-attachments/assets/262cc0fa-e0af-4a50-8c3d-4465059418b8)

### 术语表

站点级[术语表]({{% relref "docs/guide/shortcodes/term" %}})，提供专用列表页面和用于内联定义的 `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](https://github.com/ghac101) - Umami 分析修复、禁用上一篇/下一篇导航
- [@pmarrapese](https://github.com/pmarrapese) - 标题 Markdown 属性支持
- [@Bubbler-4](https://github.com/Bubbler-4) - details 短代码文档
- [@bloovis](https://github.com/bloovis) - FlexSearch 结果计数修复
- [@AntoninPvr](https://github.com/AntoninPvr) - 卡片副标题定位修复
- [@illia-v](https://github.com/illia-v) - 移动端目录和搜索切换修复
- [@gallochri](https://github.com/gallochri) - 意大利语本地化
- [@MatheusFlausino](https://github.com/MatheusFlausino) - LLMs.txt 排除
- [@daniseijo](https://github.com/daniseijo) - 最后修改作者功能
- [@confusedkernel](https://github.com/confusedkernel) - 归档页面
- [@Fenyutanchan](https://github.com/Fenyutanchan) - Hugo v0.156.0 RSS 作者兼容性修复

同时感谢回归贡献者 [@KStocky](https://github.com/KStocky)、[@ldez](https://github.com/ldez)、[@kowyo](https://github.com/kowyo)、[@torbjornbp](https://github.com/torbjornbp)、[@yuri1969](https://github.com/yuri1969) 和 [@PrintN](https://github.com/PrintN) 的持续贡献。

---

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