文档

新增：本站文章转为文档

• 在文档库列表、文档库操作菜单和文档管理页增加「导入本站文章」。支持标题搜索、分页和跨页多选，单次最多 100 篇，排除回收站文章。
• 可导入到已有文档库或新建文档库。复制文章最新已保存内容，保留原文章；新文档默认草稿，可选择立即发布。
• Markdown 原文保留；富文本自动转换为 Markdown，图片和附件继续引用原地址，复杂组件尽量保留 HTML 并提示检查。
• 同一篇文章再次导入同一文档库时，按来源标识更新标题和正文，保留文档位置、别名、发布状态、发布时间及自定义代码。来源关联随备份导出和恢复。
• 展示逐篇导入结果，支持只重试失败文章。

修复与构建校验

• 修复富文本转换时把标题和编辑器 ID 输出为 {#…} 的问题，避免正文出现编码后的锚点字符串；不删除原 Markdown 或代码中的同类文字。
• 递增插件版本，避免同版本替换后 Halo Console 合并脚本继续引用旧 JS/CSS，造成页面持续加载及资源 404。
• 构建时校验安装包中的全部 UI chunk 引用，防止缺失资源的安装包通过验证。

升级说明

• 适用于 Halo >= 2.25.0。从附件下载 plugin-my-docs-1.7.6.jar，在 Halo Console 插件页升级。
• 非超级管理员使用导入功能前，需要为角色授予「本站文章导入」权限，该权限依赖文档管理和 Halo 文章查看权限。
• 旧版本已导入的多余 {#…} 标记不会自动改写：升级后重新导入对应文章到同一库即可更新。重新导入会覆盖文档正文中的手动修改，请先备份需要保留的编辑。
• 升级后刷新整个 Console 页面；若仍请求旧 chunk，可强制刷新，并检查合并脚本的 CDN／反向代理缓存。

验证

• 后端 180 项测试、前端 67 项测试通过。
• 完整构建及安装包 UI 资源引用校验通过。
• 已在实际站点验证页面加载、文章转换及锚点标记修复符合预期。

---

Generated from v1.7.6

根因

设置服务会把同一主机的签名凭证归并成「单个元素、内嵌换行」的形态（host: access: X + 换行 + host: secret: Y），而签名解析把列表元素当作一行处理——归一化形态的值因包含换行被防注入检查整条拒绝。自 1.6.4 引入 SigV4 支持以来，通过设置页配置的签名凭证从未真正生效过，私有桶请求全部以未签名发出，R2 回 400 InvalidArgument / Authorization。

此前的测试直接注入逐行形态的凭证，恰好绕过了归一化这一环，因此一直未能发现。

修复

• parseSigningRules 先把每个元素按行拆开再解析：设置页保存的「一行一条」与设置服务归一化后的「内嵌换行」两种形态均支持；防注入检查保留（拆行后的值不再包含换行）。
• 新增走完整链路的回归测试：UI 两行凭证 → 设置服务归一化 → 代理签名，断言 Authorization 头存在；并对真实 R2 私有桶验证同一链路可正常流式取回。

升级

升级到 1.7.4 后无需重新配置，已保存的签名凭证即刻生效。

---

Generated from v1.7.4

问题背景

生产环境出现 上游拒绝：400 InvalidArgument - Authorization：这是 R2 对完全未携带签名的请求的回应（签名错误会是 403 SignatureDoesNotMatch）。说明媒体代理的签名凭证规则没有生效——可能是未配置，也可能是配置的行被静默丢弃（主机与允许清单不一致、access/secret 未成对等）。

改进

• 502 报错自动区分「未签名被拒」：当上游回 InvalidArgument/Authorization 且本次请求未携带签名时，报错追加指引——去「文档设置 → 媒体同域代理 → 签名凭证」为该主机配置成对的 access 与 secret（已签名的请求不追加，避免误导）。
• 设置解析丢弃凭证规则时，服务端日志输出 WARN（凭证值一律脱敏为 ***）：格式错误的行、主机不在允许清单内的规则、access/secret 未成对的组，都能在 Halo 日志里直接看到被忽略的原因。

---

Generated from v1.7.3

修复

视频播放：媒体代理此前把上游响应体整段缓冲（≤8 MiB 进内存、更大落临时文件）后才回给浏览器，导致：

• 视频首帧要等完整下载完成，大文件表现为长时间黑屏转圈；
• 每次拖动进度条都触发一次全量重新拉取；
• 播放器放弃旧请求后，服务端仍在继续白下载。

本版改为流式转发：上游响应头一到即回给浏览器，响应体边收边转；Range 请求原样透传，拖动进度条只取所需片段；浏览器断开时取消信号传回上游。服务端不再整段缓冲、不再落临时文件。

其他改进

• 上游错误状态（非 XML 响应体）如实报上游状态码，不再误报 415。
• 地址已带 X-Amz-Signature 等预签名参数时不再叠加 SigV4 签名头，避免双重鉴权被 S3 拒绝。
• 关闭压缩协商，上游字节原样透传，避免视频流被中途解压破坏。

验证

• 新增回归测试：首帧时序、取消传导、Range 字节一致性；全套 151 个测试通过。
• 对真实 R2 私有桶端到端验证：无凭证报错可读、签名全量取回、Range 三段字节一致、HEAD 正常。

---

Generated from v1.7.2

v1.7.1：上游错误文档不再误报 415

修复

• 对象存储的鉴权失败与对象不存在都返回 application/xml。此前一律按「415 上游内容类型不允许」
  拒绝，把排查方向引到内容类型上，而真正的原因（AccessDenied、InvalidArgument 等）躺在响应体里。
  现在这类响应会读出 /，报成 502 并带上错误码与说明。
• 日志同时打印上游状态码与错误文档片段。

保留

• 类型闸门不变：非 XML 的 text/html、image/svg+xml 等仍按 415 拒绝。

测试

• 新增 4 条用例（R2 的 InvalidArgument/Authorization、AccessDenied、无 Code 标签、非 XML 仍 415）。
• Java 用例 139 → 143。

---

Generated from v1.7.1

v1.7.0：文档设置页改版

改进

• 分组导航：七个分组（备份与恢复、基础设置、文档库首页布局、文档页面渲染、视频与媒体代理、
  全局自定义代码、AI 辅助编写）一键跳转，滚动时高亮当前分组；窄屏变成顶部粘性横向条。
• 常驻保存栏：显示「有未保存的改动 / 当前设置已保存」，无改动时保存按钮置灰。
• 媒体代理的允许主机、签名凭证、附加请求头、大小上限收进折叠区，打开代理开关时自动展开。
• 布局列表分组显示条数。

修复

• 保存失败时曾立即显示「已保存」并禁用保存按钮，用户看不到错误也无法重试；
  现在落库成功后才更新已保存状态，失败提示并保持可重试。
• 滚动高亮此前只监听 window。Halo 控制台外壳用 OverlayScrollbars 内部滚动，
  window 上不会有 scroll 事件，分组高亮会永远停在第一项；现在自动识别真正的滚动容器，
  点击导航也会同步选中。
• 整页装得下视口时不再误判为「滚到底」而高亮最后一个分组。

测试

• 新增 settings-navigation（分组清单、滚动判定、改动检测、滚动容器识别）10 条用例。
• my-docs-settings 新增「每个声明字段都必须能往返」用例，防止保存时静默丢字段。
• UI 用例 45 → 56，全部通过；Java 用例 139 个不变。

---

Generated from v1.7.0

v1.6.4：媒体代理支持 S3 SigV4 签名凭证，私有桶可用

修复

• 私有桶此前根本用不了：R2 / S3 的 API 不接受静态 Authorization 头，
  GetObject 必须带按请求算出来的 SigV4 签名，靠「附加请求头」填固定值填不出来
  （填 Bearer 会得到 400/403，表现为 502）。
• 新增「媒体代理签名凭证」设置项：每行「主机: 键: 值」，键取 access、secret 与可选
  region，插件在每次请求时现算签名头。

新增

• AwsSigV4Signer：纯 JDK 的 AWS Signature V4 实现（HMAC-SHA256），
  对照 AWS 文档 IAM 示例向量校验：签名
  5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924a6f2b5d7
  （期望值用一份独立实现按文档算法算出，逐字符一致）。
• 顺带修掉两处会让签名失效的问题：路径二次编码（%20 → %2520）、
  参与签名的头集合与文档示例不一致。
• MediaProxySignedRequestTest：桩上游抓出真正发出去的请求头，按上游视角复算签名，
  确保中间层没有改写 Authorization；凭证不会带给不在允许清单里的主机。
• 测试：Java 127 → 139。

提示

• 凭证以明文存放在站点 ConfigMap 里，请授予只读权限并定期轮换。

---

Generated from v1.6.4

v1.6.3：修复匿名访客访问媒体代理被重定向到登录页

修复

• 匿名访客访问 media-proxy 会被 302 到 /login?authentication_required，
  表现是前台视频资源加载失败，而管理员的浏览器（已登录）会走到上游类型检查，
  于是同一个功能对不同人报出不同的错。
• 根因：Halo 的 RequestInfoFactory 会把 /apis/{group}/{version}/{资源} 判成资源请求
  （resource=media-proxy、verb=get），nonResourceURLs 规则匹配不到这类路径，
  匿名角色必须把资源名逐个写进 resources。此前只声明了 nonResourceURLs，
  同一规则里的 libraries 之所以能用，是因为它另有资源规则。
• 公开资源清单补上 media-proxy，并在 roleTemplates.yaml 注释里写明这个坑。

测试

• 新增 PublicEndpointRoleTest，把公开端点的资源清单与匿名角色对起来；
  已用「临时移除 media-proxy」验证过它会失败。
• 公网用例超时放宽到 180 秒，避免跑整套用例时因外部站点变慢而误报。
• Java 用例 123 → 127。

同时包含 v1.6.2 的内容：媒体代理放行 application/octet-stream 对象并按 URL 扩展名
推断类型（对象存储里没带 Content-Type 的视频此前会被 415 挡掉）。

---

Generated from v1.6.3

v1.6.2：媒体代理放行 octet-stream 对象并按扩展名推断类型

修复

• 对象存储里上传时没带 Content-Type 的对象会返回 application/octet-stream，
  媒体代理此前按「不是 video/* 就拒」处理，直接回 415，明明能播的视频播不了。
• 判定改为三步：白名单类型（video/ audio/ image/）直接放行；明确危险的类型
  （text/html、image/svg+xml、application/xml、JavaScript 等）一律拒绝；其余
  按 URL 扩展名推断（webm → video/webm、m3u8 → application/vnd.apple.mpegurl 等）。
• 放行后响应类型改成推断结果；扩展名兜底命中图片时补 Content-Disposition: attachment；
  所有响应统一带 X-Content-Type-Options: nosniff。
• 没有可用扩展名且类型不可识别时仍然拒绝，不猜。
• 拒绝时把上游实际类型与地址写进 WARN 日志，便于排查。

测试

• 新增 MediaTypePolicyTest（6 个用例）与三条桩客户端用例：octet-stream 视频放行并改写类型、
  HTML 伪装成 .png 仍拒绝、无扩展名的二进制仍拒绝。Java 用例 114 → 123。

---

Generated from v1.6.2

v1.6.1：文档设置页补齐媒体代理与阅读增强设置项

修复

• 文档设置页此前不认识 renderCopyButtons、renderImageZoom、renderMediaEmbed
  与四个 mediaProxy* 字段：这些项只写在 settings.yaml 里，而文档设置页是自绘表单，
  结果既不显示，保存时还会整组覆盖 ConfigMap 把它们静默清空。
• 现在「代码块与公式渲染」一节补上「复制按钮」「图片点击放大」，
  新增「视频与媒体代理」一节：媒体同域代理开关、允许主机清单、附加请求头、大小上限。
• 设置解析补齐这 7 个字段：多行文本与数组两种形态都能读回来，大小上限钳制在
  1048576 - 2147483647，并补测试守住「解析后序列化不丢字段」。

说明

• 媒体同域代理默认关闭；允许清单留空时不做任何改写。
• 该端点对访客开放，凭证规则只按主机匹配、没有路径限制，配了凭证即等于把该主机
  对公网开放读取；设置页与 README 都标注了这一点。

---

Generated from v1.6.1

v1.6.0：媒体同域代理与前台明暗切换

新功能

• 同域媒体代理：新增 media-proxy 端点与「媒体同域代理」设置组。
  把允许清单内主机的图片、音视频地址改写为站点自身的
  /apis/api.my-docs.tsdaer.run/v1alpha1/media-proxy?src=… 由服务端代取，
  前台只与站点同域通信。适用于对象存储桶不对外开放、Halo 附件只记录
  裸对象地址（浏览器直连返回 400 InvalidArgument / Authorization）的情况。
  支持 *.example.com 通配主机、可选凭证请求头、大小上限；超限在响应流上截断；
  8 MiB 以内走内存，更大落临时文件流式回放。
• 前台明暗切换按钮：访客手动选择后优先于站点主题与系统偏好，记在浏览器本地，
  刷新保持，宿主主题写在根元素上的 dark 标记不会把手动浅色压回去。
• 后台从附件库插入视频改用图片语法 ，标签取附件标题或文件名。
• 记住附件弹窗打开前的光标位置，插入落回该位置而不是文档末尾。

修复

• 端点清理时机：临时文件曾在 WebFlux 开始写响应体之前被删除，
  大于 8 MiB 的媒体全部返回 500、客户端收到 0 字节。
• 媒体代理大小上限未生效：改为在响应流上按字节截断，不再信任上游声明的
  Content-Length（此前声明 1 KiB 实发 12 MiB 会把整个文件读进堆）。
• 普通域名被误判为 IPv6 私网地址（cdn.example.com 这类全十六进制字符域名被拒）。
• :443 显式端口与尾点域名匹配不上允许清单，私有桶场景下等于既没代理、直连也打不开。
• 带端口的凭证规则把端口当成头名，导致规则静默失效并向上游发出垃圾头。
• 204 之类的 2xx 响应丢弃已落地的响应体，导致临时文件泄漏。
• 附件标签在非法百分号编码时抛 URIError。

升级提示

• 媒体同域代理默认关闭；允许清单留空时端点一律 404。
• 该端点对访客开放，凭证规则只按主机匹配、没有路径限制：配了凭证即等于
  把该主机对公网开放读取。请只把确实需要公开的媒体主机写进允许清单。
• 文档渲染设置新增四个媒体代理设置项；主题切换按钮出现在 /docs 三个页面右上角。

---

Generated from v1.6.0

新增

• 复制按钮：代码块、图片和块级公式右上角悬停显示复制按钮——代码块复制源码，图片转 PNG 写入剪贴板（跨域等失败时自动降级为复制图片链接），公式复制 LaTeX 源码；同时替换 Vditor 内置的代码复制按钮，样式统一随明暗主题。
• 图片点击放大：点击正文图片以灯箱形式查看大图，支持点击遮罩、关闭按钮或 ESC 关闭；图片被链接包裹时仅在链接指向图片文件时放大原图，普通页面链接不受影响。
• 视频内嵌播放：图片语法引用 mp4 / webm / ogv / ogg / m4v / mov / m3u8 文件时渲染为内嵌播放器（DPlayer），m3u8 通过 hls.js 支持，加载失败自动回退原生播放器；#md-width / #md-align 等图片参数继续有效，普通链接保持链接语义。
• 图表主题适配：明暗模式切换时全部图表（Mermaid、ECharts、flowchart、graphviz、mindmap、markmap、plantuml、abc、SMILES）自动恢复源码重渲染换肤；ECharts 与 mindmap 背景改为透明融入页面，配色以主题强调色（--mdocs-accent）为主色自动生成，并修复图表容器无高度不可见的问题。

设置

• 新增三个渲染开关（默认开启）：复制按钮、图片点击放大、视频内嵌播放。

---

Generated from v1.5.0

新增

• 从 Wiki 更新：重复导入同一 Wiki 到已有文档库时，按别名或页面名（忽略大小写）匹配到的已有文档原地更新标题与正文（沿用原别名，外部链接不失效），其余按新建处理；导入报告新增「更新 N 篇」统计。
• 普通 Markdown 相对链接（如 [文字](Page-Name.md)）在导入时同样按页面名大小写不敏感解析并转换为站内同库短链接，修复 GitHub 端链接大小写与文件名不一致导致的跳转失败。

---

Generated from v1.4.0

摘要

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

本版本为 v1.3.1，适用于 Halo >= 2.25.0。

v1.3.0 的产物因 fat jar 中残留 JGit 签名文件无法加载，已撤回；请使用本版本。

本版重点

GitHub Wiki 导入

• 双通道导入：输入 owner/repo 或完整 GitHub 地址由服务器浅克隆 .wiki.git 拉取（私有 Wiki 支持 PAT 令牌）；服务器无法直连 GitHub 时可上传 clone 后打包的 zip
• Wiki 链接自动转换：[[Page]]、[[Page|文字]]、[[Page#锚点]] 转换为站内同库短链接；找不到对应页面时降级为纯文本并在导入报告中提示
• 导入行为：页面文件名作为标题，Home 排最前；_Sidebar / _Header / _Footer 自动跳过；可选导入到已有文档库（别名冲突自动追加序号）或新建文档库；可指定导入后立即发布或保持草稿

优化与修复

• 加固文档端点校验：PUT 路径名与请求体一致性、所属文档库存在性
• 搜索索引同步去重：插件重启后的全量 resync 不再反复重建索引；修复文档删除后搜索索引残留
• Markdown 渲染器实例复用，提升阅读页渲染性能
• 修复 fat jar 残留签名文件导致插件加载失败（Invalid signature file digest）

安装

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

---

Generated from v1.3.1

摘要

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

本版本为 v1.3.0，适用于 Halo >= 2.25.0。

本版重点

GitHub Wiki 导入

• 双通道导入：输入 owner/repo 或完整 GitHub 地址由服务器浅克隆 .wiki.git 拉取（私有 Wiki 支持 PAT 令牌）；服务器无法直连 GitHub 时可上传 clone 后打包的 zip
• Wiki 链接自动转换：[[Page]]、[[Page|文字]]、[[Page#锚点]] 转换为站内同库短链接；找不到对应页面时降级为纯文本并在导入报告中提示
• 导入行为：页面文件名作为标题，Home 排最前；_Sidebar / _Header / _Footer 自动跳过；可选导入到已有文档库（别名冲突自动追加序号）或新建文档库；可指定导入后立即发布或保持草稿
• 导入入口位于文档库列表页、文档库行内菜单与文档管理页

优化与修复

• 加固文档端点校验：PUT 路径名与请求体一致性、所属文档库存在性
• 搜索索引同步去重：插件重启后的全量 resync 不再反复重建索引；修复文档删除后搜索索引残留
• Markdown 渲染器实例复用：前台每页视图渲染不再重建解析器实例，提升阅读页性能
• 修复开发工具链：eslint 无法加载 TypeScript 配置的问题

安装

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

升级

1. 备份当前 Halo 数据。
2. 在维护窗口内上传新版本 jar。
3. 启用后检查：文档库列表是否正常加载、搜索索引是否完整。

---

Generated from v1.3.0

升级提示

• 本版本要求 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 会继续保留。

---

Generated from v1.2.1

升级提示

• 本版本要求 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 会继续保留。

---

Generated from v1.2.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 辅助编写:文档设置页提供「后台代码片段」与「扩展插件开发」提示词一键复制