Hextra v0.13

September 29, 2026·

Hextra v0.13.0 带来了全新的搜索体验（在移动端和桌面端都同样流畅）、带灯箱的图片库短代码、可折叠提示框、远程图标包，以及改进的 Jupyter 笔记本渲染，同时包含搜索可靠性改进和错误修复。

升级指南

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

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

如果您使用 CSS 自定义了搜索界面，请参阅搜索 CSS 变更。

亮点

全新的搜索体验，在移动端和桌面端都同样流畅
图片库短代码，提供 PhotoSwipe 灯箱以及网格、轮播和拼贴布局
可折叠提示框，支持自定义标题，兼容 Obsidian callouts
远程图标包：Lucide、Tabler Icons 和 Simple Icons
改进的 Jupyter 笔记本渲染，支持 In/Out 提示符和更多输出类型
自定义页面部分 partial，可在页面正文前后注入内容
为搜索数据文件添加指纹（fingerprint），搜索结果更简洁

新功能

全新的搜索体验

New search dialog on desktop

搜索功能已全面重新设计为命令面板式对话框，在移动端和桌面端都同样流畅。在桌面端，可在任意页面按 ⌘+K（Windows 和 Linux 上为 Ctrl+K）或 / 打开搜索；在移动端，点击导航栏中的搜索图标即可打开同样完整的搜索对话框。

搜索结果带有面包屑标签，便于了解每条结果所在的位置；整个对话框都可以通过键盘操作，打开和关闭时也有流畅的动画。如果希望在桌面端同样使用仅图标的触发按钮，可在搜索菜单项上设置 params.icon：

hugo.yaml

menu:
  main:
    - name: Search
      weight: 5
      params:
        type: search
        icon: search

搜索结果现在也更加简洁：摘要中的 HTML 标签会被移除，标题锚点中的内联标记得到正确处理，并且搜索数据文件在生产环境中会添加指纹（fingerprint），部署后索引更新可立即生效。

图片库短代码

新的 gallery 短代码用于展示一组图片，提供交互式 PhotoSwipe 灯箱，包括全屏查看、上一张/下一张导航、图片说明和键盘支持。

{{< gallery >}}
  {{< gallery-item src="https://picsum.photos/id/1015/1600/1200" thumb="https://picsum.photos/id/1015/800/600" width="1600" height="1200" caption="河谷" >}}
  {{< gallery-item src="https://picsum.photos/id/1018/1600/1200" thumb="https://picsum.photos/id/1018/800/600" width="1600" height="1200" caption="高山湖泊" >}}
  {{< gallery-item src="https://picsum.photos/id/1019/1600/1200" thumb="https://picsum.photos/id/1019/800/600" width="1600" height="1200" caption="林间小径" >}}
{{< /gallery >}}

通过 type 参数可选择三种布局类型：统一的 grid 网格（默认）、可横向滚动的 carousel 轮播，以及允许项目跨越多列或多行的 mosaic 拼贴布局。图片来源支持本地页面资源包、全局资源、静态文件和远程 URL。

可折叠提示框

提示框现在支持扩展语法，可实现内容折叠和自定义标题。在提示框类型后添加 + 或 - 使其可折叠，标记后的文字将作为标题。该语法兼容 Obsidian callouts。

Markdown

> [!TIP]- 提示框可以折叠吗？
> 可以。可折叠提示框在收起时会隐藏内容。

可以。可折叠提示框在收起时会隐藏内容。

远程图标包

除内置的 Heroicons 图标集外，图标现在可以通过提供方前缀从远程图标包按需加载：

提供商	示例	图标
Lucide	`{{< icon "lucide:rocket" >}}`
Lucide	`{{< icon "lucide:sparkles" >}}`
Tabler Icons	`{{< icon "tabler:brand-github" >}}`
Tabler Icons	`{{< icon "tabler:database" >}}`
Simple Icons	`{{< icon "simple:hugo" >}}`
Simple Icons	`{{< icon "simple:markdown" >}}`

支持的提供方包括 Lucide、Tabler Icons 和 Simple Icons。图标在构建时获取，可用于 Hextra 中任何接受图标名称的地方，包括卡片、标签页、徽章、提示框和导航栏菜单项。

例如在徽章和卡片中使用：

{{< badge content="Hugo" icon="simple:hugo" >}}
{{< badge content="Markdown" icon="simple:markdown" >}}

{{< cards >}}
  {{< card link="https://lucide.dev/icons/" title="Lucide" icon="lucide:feather" >}}
  {{< card link="https://tabler.io/icons" title="Tabler Icons" icon="tabler:brand-tabler" >}}
  {{< card link="https://simpleicons.org/" title="Simple Icons" icon="simple:simpleicons" >}}
{{< /cards >}}

Hugo

Markdown

Lucide

Tabler Icons

Simple Icons

改进的 Jupyter 笔记本渲染

jupyter 短代码得到大幅改进，现在支持错误回溯、stderr 流、SVG、Markdown、LaTeX、JSON、原始单元格、附件、输出元数据以及单元格可见性元数据。通过新的 prompts 参数可显示 Jupyter 风格的 In [N]:/Out[N]: 执行提示符：

{{< jupyter src="notebook.ipynb" prompts=true >}}

自定义页面部分

新的自定义钩子允许通过在站点中创建以下任意 partial，在每个页面正文前后注入内容：

layouts/_partials/custom/page-begin.html
layouts/_partials/custom/content-begin.html
layouts/_partials/custom/content-end.html
layouts/_partials/custom/page-end.html

每个 partial 都以当前 Hugo 页面作为上下文。

搜索 CSS 变更

内联搜索框已被对话框取代，因此 hextra-search-wrapper 类已移除。如果您使用 CSS 自定义了搜索界面，请改用新的 hextra-search-trigger 和 hextra-search-dialog 类。完整的搜索类列表请参阅自定义 CSS 文档。

修复

页面加载时立即渲染可见的 Mermaid 图表
修复偏好减少动态效果时 Mermaid 图表的缩放
为 Hugo 数学渲染器选择兼容的 KaTeX CSS
侧边栏没有页面条目时，移动端菜单回退到页面树
在链接渲染钩子中解析页面相对 Markdown 链接
处理搜索中标题片段的内联标记
更新 Hugo 语言配置键至最新约定
导航栏图标菜单项现在支持 tel: 等非 HTTP 链接
修复卡片和链接中 HTML 属性之间缺少空格的问题，以及嵌套 hero 短代码中标签未闭合的问题
修复图片库短代码在 Windows 上的构建错误

贡献者

感谢此版本的贡献者：

@bombsimon - 从搜索结果中移除 HTML 标签
@yuri1969 - 减少动态效果时的 Mermaid 图表缩放修复
@muhammadkholidb - 在展示页中添加 Roled 文档
@farmacia-cambie - 导航栏图标菜单项支持 tel: 链接
@hoshsadiq - 修复 HTML 属性间距和嵌套 hero 短代码
@avighnac - 修复图片库短代码在 Windows 上的构建

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

最后更新于 September 29, 2026

Hextra v0.12