博客
Hextra v0.10

Hextra v0.10

August 14, 2025·imfing
imfing

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

新功能

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

导航栏下拉菜单支持

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

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 文件。

示例 llms 文本

目录滚动高亮

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

目录滚动高亮效果

同步标签页切换

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

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 的站点

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 位新贡献者的代码提交：

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

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

最后更新于
Markdown 语法指南