v1.2.1 - 明暗主题渲染增强与 RaTeX 数学公式

升级提示

• 本版本要求 Halo >= 2.25.0。
• 内容主题设置已完成重构，不再提供 Light、Dark、WeChat、Ant Design 等内置内容主题。
• 浅色与深色模式现在分别通过“自定义 CSS 地址 + 正文容器 class”配置内容样式。
• 如果旧版本正在使用内置内容主题，升级后请前往「文档设置」重新配置自定义 CSS；未配置 CSS 或加载失败时，阅读页会使用基础回退样式。
• 自定义 CSS 地址仅支持 HTTPS 地址或以 / 开头的站内绝对路径。
• 升级前建议通过「文档设置」导出当前设置和文档快照，并备份 Halo 数据。

新功能

明暗模式独立渲染配置

• 浅色与深色模式可分别配置：
  • 自定义 Markdown CSS 地址
  • 正文容器 class
  • highlight.js 代码高亮主题
• 优先识别 Halo 当前主题状态。
• Halo 使用 auto 或未提供明确主题状态时，自动跟随浏览器的 prefers-color-scheme。
• 主题变化后无需重新生成正文 HTML，即可切换内容 CSS、正文 class 和代码主题。
• 增强对常见主题 class、data 属性和本地存储主题状态的兼容。

RaTeX 数学公式渲染

• 新增对 $...$ 行内公式和 $$...$$ 块级公式的渲染支持。
• 使用 RaTeX WASM + Canvas 在浏览器端渲染公式。
• Canvas 背景保持透明，公式颜色自动跟随正文实际颜色。
• 明暗主题切换后自动重新绘制公式颜色。
• RaTeX 初始化或单个公式渲染失败时，自动回退到 Vditor 数学公式渲染。
• RaTeX、WASM、字体及相关资源均由插件本地提供，无需依赖外部 CDN。

Markdown 渲染增强

新增或完善以下前台渲染选项：

• 代码块行号
• 中英文与数字之间自动空格
• 裸 URL 自动链接
• Markdown 脚注
• ==文字== Mark 标记
• 常见技术术语大小写修正
• 正文顶层段落首行缩进
• Mermaid、Graphviz、ECharts、Markmap 等图表代码块渲染

以上设置仅作用于前台文档阅读页，不会改变后台 Vditor 编辑器的行为。

改进

• 优化文档设置页的渲染配置布局，使用浅色 / 深色标签分别管理对应设置。
• 移除效果不稳定的内置内容主题选择，统一改为自定义 CSS 配置。
• 自定义 CSS 留空或加载失败时保留可读的基础回退样式。
• 优化主题切换过程中的代码主题和公式颜色刷新逻辑。
• 修复快速连续切换明暗主题时，旧的延迟刷新可能覆盖当前公式颜色的问题。
• 调整文档设置页与文档编辑页的自定义代码输入框布局。
• 规范插件 YAML 配置值格式。
• 更新文档设置页截图及相关使用文档。

构建与发布

• 构建流程新增 RaTeX 静态资源处理任务。
• Vditor、RaTeX、WASM 和数学字体资源会随插件 JAR 一并打包。
• 新增静态资源反向代理配置，确保前台渲染资源可正常访问。
• 完善自动发布流程，支持发布至 Halo 应用市场。

兼容性

• Halo：>= 2.25.0
• Java：21+
• 从 v1.1.0 升级时，原有文档库、文档内容、自定义代码、布局配置和代码主题配置均可继续使用。
• 旧的内置内容主题名称不再生效；已有自定义 CSS 地址与正文 class 会继续保留。

v1.2.0 - 明暗主题渲染增强与 RaTeX 数学公式

升级提示

• 本版本要求 Halo >= 2.25.0。
• 内容主题设置已完成重构，不再提供 Light、Dark、WeChat、Ant Design 等内置内容主题。
• 浅色与深色模式现在分别通过“自定义 CSS 地址 + 正文容器 class”配置内容样式。
• 如果旧版本正在使用内置内容主题，升级后请前往「文档设置」重新配置自定义 CSS；未配置 CSS 或加载失败时，阅读页会使用基础回退样式。
• 自定义 CSS 地址仅支持 HTTPS 地址或以 / 开头的站内绝对路径。
• 升级前建议通过「文档设置」导出当前设置和文档快照，并备份 Halo 数据。

新功能

明暗模式独立渲染配置

• 浅色与深色模式可分别配置：
  • 自定义 Markdown CSS 地址
  • 正文容器 class
  • highlight.js 代码高亮主题
• 优先识别 Halo 当前主题状态。
• Halo 使用 auto 或未提供明确主题状态时，自动跟随浏览器的 prefers-color-scheme。
• 主题变化后无需重新生成正文 HTML，即可切换内容 CSS、正文 class 和代码主题。
• 增强对常见主题 class、data 属性和本地存储主题状态的兼容。

RaTeX 数学公式渲染

• 新增对 $...$ 行内公式和 $$...$$ 块级公式的渲染支持。
• 使用 RaTeX WASM + Canvas 在浏览器端渲染公式。
• Canvas 背景保持透明，公式颜色自动跟随正文实际颜色。
• 明暗主题切换后自动重新绘制公式颜色。
• RaTeX 初始化或单个公式渲染失败时，自动回退到 Vditor 数学公式渲染。
• RaTeX、WASM、字体及相关资源均由插件本地提供，无需依赖外部 CDN。

Markdown 渲染增强

新增或完善以下前台渲染选项：

• 代码块行号
• 中英文与数字之间自动空格
• 裸 URL 自动链接
• Markdown 脚注
• ==文字== Mark 标记
• 常见技术术语大小写修正
• 正文顶层段落首行缩进
• Mermaid、Graphviz、ECharts、Markmap 等图表代码块渲染

以上设置仅作用于前台文档阅读页，不会改变后台 Vditor 编辑器的行为。

改进

• 优化文档设置页的渲染配置布局，使用浅色 / 深色标签分别管理对应设置。
• 移除效果不稳定的内置内容主题选择，统一改为自定义 CSS 配置。
• 自定义 CSS 留空或加载失败时保留可读的基础回退样式。
• 优化主题切换过程中的代码主题和公式颜色刷新逻辑。
• 修复快速连续切换明暗主题时，旧的延迟刷新可能覆盖当前公式颜色的问题。
• 调整文档设置页与文档编辑页的自定义代码输入框布局。
• 规范插件 YAML 配置值格式。
• 更新文档设置页截图及相关使用文档。

构建与发布

• 构建流程新增 RaTeX 静态资源处理任务。
• Vditor、RaTeX、WASM 和数学字体资源会随插件 JAR 一并打包。
• 新增静态资源反向代理配置，确保前台渲染资源可正常访问。
• 完善自动发布流程，支持发布至 Halo 应用市场。

兼容性

• Halo：>= 2.25.0
• Java：21+
• 从 v1.1.0 升级时，原有文档库、文档内容、自定义代码、布局配置和代码主题配置均可继续使用。
• 旧的内置内容主题名称不再生效；已有自定义 CSS 地址与正文 class 会继续保留。

v1.1.0 - 迁移自有命名空间并收窄权限

⚠️ 升级须知（重要）

• 本版本将自定义资源的 API group 从 docs.halo.run 迁移到 my-docs.tsdaer.run。
  在旧版本下已创建的文档 / 文档库数据存储于旧 group，升级后新版本将无法读取到这些旧数据
  （文档列表会显示为空）。请在生产环境升级前做好评估与备份。全新安装不受影响。
• 升级后请强制刷新浏览器缓存（Ctrl+Shift+R 或使用无痕窗口），确保加载新的前端资源。

🐛 修复市场审核问题

• 命名空间迁移：自定义资源与 API group 由 Halo 官方 halo.run 命名空间迁移至开发者自有命名空间
  （docs.halo.run → my-docs.tsdaer.run，含公开 API、Console API 与搜索索引），避免与平台能力混淆。
• 收窄 ConfigMap 权限：「文档管理」角色不再拥有全站 ConfigMap 读写权限，改为仅限本插件自身的
  my-docs-configmap（resourceNames 限定 get/update/patch），消除越权访问其他系统/插件配置的风险。

✨ 优化

• 后台菜单调整：将「文档」「文档设置」从「内容」区移至独立的「文档」分组，结构更清晰。

🔧 构建

• 提升插件版本号，确保客户端正确加载新版前端资源。
• 构建前清理旧的 UI 产物，避免陈旧 chunk 被打入发行包。

my-docs v1.0.0

my-docs 为 Halo 提供独立的文档 / 知识库系统,支持文档库、树形目录、Markdown 编辑、前台文档站点、搜索与 SEO 集成。

首个正式版本 v1.0.0,适用于 Halo >= 2.25.0。

主要功能

• 文档库管理:创建、编辑、删除文档库,支持描述与封面
• 树形编排:在 Console 中拖拽调整目录树与同级顺序,支持父子层级与排序权重
• Markdown 编辑:独立 Vditor 编辑器,支持从 Halo 附件库插入图片、附件与站内文档链接
• 前台文档站点:提供 /docs、/docs/{librarySlug}、/docs/{librarySlug}/{docSlug} 页面,含侧边目录树与可配置布局的文档库首页
• 阅读增强:正文大纲、滚动高亮、同库标题短链接跳转、移动端折叠目录,并跟随 Halo 主题切换
• 搜索与 SEO:已发布文档接入 Halo 搜索,并输出页面级 SEO 元信息
• 公共访问接口:仅暴露已发布文档的只读 API,避免草稿泄露
• 备份与恢复:文档设置页支持导出 / 加载设置,快照含插件设置、文档库与文档 Markdown 内容
• 自定义代码注入:支持在全局、文档库、单篇文档三个层级注入自定义 head / body 代码(HTML / CSS / JS),按 全局 → 文档库 → 文档 顺序叠加
• 扩展点机制:对外开放 DocContentHandler(正文后处理)与 DocDetailModelHandler(阅读页 Model 注入)两个扩展点
• AI 辅助编写:文档设置页提供「后台代码片段」与「扩展插件开发」提示词一键复制

安装

1. 在下方 Release 附件中下载 plugin-my-docs-1.0.0.jar
2. 进入 Halo Console →「插件」页面并上传该 jar
3. 安装并启用 my-docs

启用后,Console 侧边栏出现「文档」与「文档设置」入口,前台访问 /docs 即可。

兼容性

• Halo:>= 2.25.0
• Java:21+

已知限制

• 当前未集成文档评论能力

my-docs v1.0.0-rc.2

my-docs 为 Halo 提供独立的文档 / 知识库系统，支持文档库、树形目录、Markdown 编辑、前台文档站点、搜索与 SEO 集成。

这是 v1.0.0-rc.2 预发布版本，主要用于验证 GitHub Release / CD 打包与分发流程，不建议作为最终正式版长期使用。

当前能力

• 文档库管理：创建、编辑、删除文档库，并支持描述与封面
• 文档树管理：支持父子层级调整、拖拽排序与同级重排
• Markdown 编辑：支持附件库插入图片、文件和站内文档链接
• 前台文档站点：提供 /docs、/docs/{librarySlug}、/docs/{librarySlug}/{docSlug} 页面
• 文档阅读体验：支持侧边目录树、正文大纲、同库标题短链接跳转
• 搜索与 SEO：已发布文档可被 Halo 搜索索引，并输出页面级 SEO 元信息

本次用途

• 验证 GitHub Release 是否能触发 CD
• 验证 Release 附件中是否自动生成并上传插件 jar
• 验证产物 jar 是否可被 Halo 安装

安装

1. 下载 Release 附件中的插件 jar
2. 进入 Halo Console
3. 打开「插件」页面并上传 jar
4. 安装并启用 my-docs

兼容性

• Halo >= 2.25.0
• Java 21+

已知限制

• 当前未集成文档评论能力
• 该版本为 RC 预发布版本

my-docs v1.0.0-rc.1

my-docs 为 Halo 提供独立的文档 / 知识库系统，支持文档库、树形目录、Markdown 编辑、前台文档站点、搜索与 SEO 集成。

这是 v1.0.0-rc.1 预发布版本，主要用于验证 GitHub Release / CD 打包与分发流程，不建议作为最终正式版长期使用。

当前能力

• 文档库管理：创建、编辑、删除文档库，并支持描述与封面
• 文档树管理：支持父子层级调整、拖拽排序与同级重排
• Markdown 编辑：支持附件库插入图片、文件和站内文档链接
• 前台文档站点：提供 /docs、/docs/{librarySlug}、/docs/{librarySlug}/{docSlug} 页面
• 文档阅读体验：支持侧边目录树、正文大纲、同库标题短链接跳转
• 搜索与 SEO：已发布文档可被 Halo 搜索索引，并输出页面级 SEO 元信息

本次用途

• 验证 GitHub Release 是否能触发 CD
• 验证 Release 附件中是否自动生成并上传插件 jar
• 验证产物 jar 是否可被 Halo 安装

安装

1. 下载 Release 附件中的插件 jar
2. 进入 Halo Console
3. 打开「插件」页面并上传 jar
4. 安装并启用 my-docs

兼容性

• Halo >= 2.25.0
• Java 21+

已知限制

• 当前未集成文档评论能力
• 该版本为 RC 预发布版本