mirror of
https://github.com/imfing/hextra.git
synced 2025-08-23 13:16:41 -04:00
ec007d73c0
* docs(blog): prepare for v0.10 release post * Update v0.10.md * Update v0.10.md to refine upgrade instructions and enhance blog features. Added synchronized tab switching and pagination controls, while improving the search experience and table of contents navigation. * Enhance v0.10 release documentation with detailed upgrade instructions and migration guide. Added Tailwind theme variable customization section and clarified breaking changes. Improved clarity on CSS class prefix changes for better user experience. * Update v0.10.md to enhance upgrade instructions, clarify breaking changes, and improve overall readability. Adjusted formatting for consistency and added details on asset management and user experience improvements. * Add notable new features to v0.10.md, including dropdown menu support, enhanced search experience, and blog list pagination. Updated FlexSearch upgrade details for clarity and improved migration guide by removing redundant breaking change notes. * chore: update zh-cn translation * chore: update ja translation * chore: update fa and ja translations * chore: prepare release
10 KiB
10 KiB
title, date, authors, tags
| title | date | authors | tags | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Hextra v0.10 | 2025-08-14 |
|
|
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
新功能
以下是本版本值得关注的新特性：
- 导航栏下拉菜单支持：创建层级导航菜单
- 增强搜索体验：改进全标题搜索精度
- llms.txt 支持：生成 AI 友好的站点大纲
- 目录滚动高亮：滚动时自动高亮当前章节
- 同步标签页切换：跨多组标签页同步选择状态
- 博客列表分页：为博客列表添加分页控件
- MathJax 支持：在 KaTeX 外新增数学公式渲染引擎
导航栏下拉菜单支持
在导航栏中创建下拉菜单，优化导航项组织方式。
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 工具和语言模型获取上下文参考。
outputs:
home: [html, llms]
这将在站点根目录生成 llms.txt 文件。
目录滚动高亮
滚动页面时，目录会自动高亮当前章节，使导航更加直观。
同步标签页切换
相同内容的标签页现在支持跨组同步。启用同步后，选择某个标签会更新所有包含相同项目的标签组（且会记住选择状态）。
params:
page:
tabs:
sync: true
博客列表分页
为博客列表页面添加基础分页控件。
params:
blog:
list:
pagerSize: 20 # 每页文章数
MathJax 支持
除默认的 KaTeX 外，新增 MathJax 数学公式渲染引擎支持，可按需选择。
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 v0.146.0+（扩展版）
- CSS 类前缀变更：组件 CSS 类现统一使用
hextra-前缀 - 资源管理：KaTeX 和 Mermaid 资源改为构建时下载
- 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 - KaTeX 字体、图片渲染钩子、链接处理改进
- @Zabriskije - 修复幽灵滚动问题
- @miniwater - 自定义页脚居中、图片 alt 文本优化
- @MattDodsonEnglish - Google 索引控制、OpenGraph 文档
- @KStocky - 反向分页功能
- @PrintN - 文档展示增强
- @hobobandy - 标题间距优化
- @dlwocks31 - 韩语翻译更新
- @TwoAnts - 修复 Giscus 主题切换
- @ldez - 搜索功能改进与错误修复
同时感谢长期贡献者 @deining 和 @yuri1969 在文档、翻译和技术改进方面的持续支持。
完整更新日志：https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0