mirror of
https://github.com/imfing/hextra.git
synced 2025-10-31 10:04:54 -04:00
83f3b5052e
* chore(docs): rename `exampleSite` to `docs` and create `examples` * chore(build): update build script to support new version format and source directories; add v0.10 to documentation menu
247 lines
10 KiB
Markdown
247 lines
10 KiB
Markdown
---
|
||
title: "Hextra v0.10"
|
||
date: 2025-08-14
|
||
authors:
|
||
- name: imfing
|
||
link: https://github.com/imfing
|
||
image: https://github.com/imfing.png
|
||
tags:
|
||
- Release
|
||
---
|
||
|
||
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"
|
||
```
|
||
|
||
|
||
|
||
### 增强搜索体验
|
||
|
||
- **全标题搜索**：可搜索所有层级标题内容，不限于页面标题
|
||
- **提升结果精度**：改进标题处理和链接准确性
|
||
- **修复结果导航**：搜索结果现在能正确跳转到对应章节
|
||
|
||
特别感谢 [@ldez](https://github.com/ldez) 推动搜索功能升级！
|
||
|
||
|
||
|
||
### llms.txt 支持
|
||
|
||
现支持生成 [llms.txt](https://llmstxt.org/) 格式输出，使站点内容更便于 AI 工具和语言模型获取上下文参考。
|
||
|
||
```yaml {filename="hugo.yaml"}
|
||
outputs:
|
||
home: [html, llms]
|
||
```
|
||
|
||
这将在站点根目录生成 `llms.txt` 文件。
|
||
|
||
|
||
|
||
### 目录滚动高亮
|
||
|
||
滚动页面时，目录会自动高亮当前章节，使导航更加直观。
|
||
|
||
|
||
|
||
### 同步标签页切换
|
||
|
||
相同内容的标签页现在支持跨组同步。启用同步后，选择某个标签会更新所有包含相同项目的标签组（且会记住选择状态）。
|
||
|
||
```yaml {filename="hugo.yaml"}
|
||
params:
|
||
page:
|
||
tabs:
|
||
sync: true
|
||
```
|
||
|
||
### 博客列表分页
|
||
|
||
为博客列表页面添加基础分页控件。
|
||
|
||
```yaml {filename="hugo.yaml"}
|
||
params:
|
||
blog:
|
||
list:
|
||
pagerSize: 20 # 每页文章数
|
||
```
|
||
|
||
|
||
|
||
### MathJax 支持
|
||
|
||
除默认的 KaTeX 外，新增 [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/)（v0.146.0+）以确保未来兼容性
|
||
- **数学公式服务端渲染**：默认使用 Hugo 原生渲染改进数学公式处理
|
||
- **FlexSearch 0.8 升级**：搜索引擎升级至 [FlexSearch](https://github.com/nextapps-de/flexsearch) 0.8，提升 CJK（中日韩）内容编码处理能力
|
||
- **增强资源管理**：KaTeX 和 Mermaid 资源支持从 CDN 或本地加载
|
||
|
||
## 使用体验优化
|
||
|
||
- **动态 favicon 切换**：根据色彩偏好自动更新网站图标
|
||
- **反向分页**：支持通过页面 front matter 设置 `reversePagination`
|
||
- **Google 索引控制**：新增页面参数控制是否允许 Google 索引
|
||
- **宽度处理改进**：通过 CSS 变量优化响应式设计控制
|
||
- **样式改进**：现代化 Markdown 表格和水平线样式
|
||
|
||
## 错误修复与稳定性
|
||
|
||
- **Giscus 主题同步**：评论模块现在正确跟随暗黑/明亮模式切换
|
||
- **搜索结果准确性**：修复搜索结果链接和标题转义问题
|
||
- **标签页切换**：解决非同步模式下的导航问题
|
||
- **幽灵滚动**：修复禁用页脚时出现的异常滚动行为
|
||
- **图片可访问性**：避免重复渲染 alt 文本
|
||
- **链接渲染**：改进复杂站点结构下的基础 URL 处理
|
||
|
||
---
|
||
|
||
## 迁移指南
|
||
|
||
- [**Hugo 版本要求**](#hugo-version-requirements)：需 Hugo v0.146.0+（扩展版）
|
||
- [**CSS 类前缀变更**](#css-class-prefix-changes)：组件 CSS 类现统一使用 `hextra-` 前缀
|
||
- [**资源管理**](#asset-management-for-katex-and-mermaid)：KaTeX 和 Mermaid 资源改为构建时下载
|
||
- [**Tailwind CSS v4**](#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](https://github.com/oosquare) - KaTeX 字体、图片渲染钩子、链接处理改进
|
||
- [@Zabriskije](https://github.com/Zabriskije) - 修复幽灵滚动问题
|
||
- [@miniwater](https://github.com/miniwater) - 自定义页脚居中、图片 alt 文本优化
|
||
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - Google 索引控制、OpenGraph 文档
|
||
- [@KStocky](https://github.com/KStocky) - 反向分页功能
|
||
- [@PrintN](https://github.com/PrintN) - 文档展示增强
|
||
- [@hobobandy](https://github.com/hobobandy) - 标题间距优化
|
||
- [@dlwocks31](https://github.com/dlwocks31) - 韩语翻译更新
|
||
- [@TwoAnts](https://github.com/TwoAnts) - 修复 Giscus 主题切换
|
||
- [@ldez](https://github.com/ldez) - 搜索功能改进与错误修复
|
||
|
||
同时感谢长期贡献者 [@deining](https://github.com/deining) 和 [@yuri1969](https://github.com/yuri1969) 在文档、翻译和技术改进方面的持续支持。
|
||
|
||
**完整更新日志**：https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0 |