---
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 是一个重大版本更新，包含了新功能、架构升级和体验优化。

<!--more-->

本次更新还包含了来自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