mirror of
https://github.com/imfing/hextra.git
synced 2025-08-25 06:16:45 -04:00
196 lines
6.5 KiB
Markdown
196 lines
6.5 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
|
||
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"
|
||
```
|
||
|
||
|
||
|
||
### 增强搜索体验
|
||
|
||
- **全标题搜索**：支持所有层级标题的内容检索
|
||
- **结果精准度提升**：优化标题处理和链接准确性
|
||
- **修复结果导航**：搜索结果现在能正确跳转到对应章节
|
||
|
||
特别感谢 [@ldez](https://github.com/ldez) 推动搜索功能改进！
|
||
|
||
|
||
|
||
### llms.txt 支持
|
||
|
||
现支持生成 [llms.txt](https://llmstxt.org/) 格式文件，便于 AI 工具理解站点内容：
|
||
```yaml {filename="hugo.yaml"}
|
||
outputs:
|
||
home: [html, llms]
|
||
```
|
||
|
||
|
||
|
||
### 目录滚动高亮
|
||
|
||
滚动页面时自动高亮当前章节，导航更直观：
|
||
|
||
|
||
### 同步标签页切换
|
||
|
||
相同内容的标签组现在支持状态同步：
|
||
```yaml {filename="hugo.yaml"}
|
||
params:
|
||
page:
|
||
tabs:
|
||
sync: true
|
||
```
|
||
|
||
### 博客列表分页
|
||
|
||
为博客列表添加基础分页控制：
|
||
```yaml {filename="hugo.yaml"}
|
||
params:
|
||
blog:
|
||
list:
|
||
pagerSize: 20 # 每页文章数
|
||
```
|
||
|
||
|
||
|
||
### 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 |