版本说明

本文档记录 源蝶文档（theme-mdocs） 的版本变更。

• 版本号规则：遵循 语义化版本，格式为 主版本.次版本.修订号。
• 版本号来源：以 theme.yaml 中 spec.version 为准，本文档按同一版本号记录。
• 日期格式：YYYY-MM-DD。

---

[1.0.0] - 2026-09-12

首个正式版本，可稳定用于技术文档、知识库与产品手册站点。

主题包：dist/theme-mdocs-1.0.0.zip
适用 Halo：>= 2.25.0

新增

文档体系

• 文档组归档：在主题设置中勾选一级分类作为「文档组」，归档页只展示这些分类，普通分类不会混入文档体系。
• 多级目录树：左侧导航按 Halo 分类树递归渲染，父子分类可折叠 / 展开，支持默认全展开或仅展开当前路径。
• 文档统计：文档组标题下显示「共 X 篇文章」。
• 右侧 TOC（本页目录）：自动解析正文 h2 / h3 生成目录，使用 IntersectionObserver 高亮当前阅读位置。
• 上下篇导航：同一分类内自动前后翻页。
• 复制 Markdown：内容页顶部工具栏可一键复制原始 Markdown，并支持生成当前页面的 Markdown 链接。

Docsme 插件适配

• 新增文档中心聚合页（docs.html）、项目目录页（doc-catalog.html）、文档详情页（doc.html）。
• 复用 Docsme 插件自身的导航树、内容头、版本切换与上下篇模块。
• 左侧导航可折叠展开，可配置默认全展开、是否显示文档数量。
• 支持多版本文档切换。

MiniDocs 插件适配

• 新增知识库中心页（minidocs-docs.html）与页内嵌阅读视图（minidocs-reader.html）。
• 点击知识库卡片无需跳转即可进入阅读视图，支持无刷新切换文档、浏览器前进后退、URL 参数（?kb=xx&docSlug=xx）直达。
• 阅读视图支持知识库封面 / 文档数 / 更新时间、文档树折叠、TOC、点赞、浏览次数、分享链接与复制 Markdown。
• 自动处理无权限场景（401 / 403 时提示登录）。

内容页操作工具栏

• 固定项：复制 Markdown、复制 Markdown 链接、点赞（Docsme / MiniDocs 文档）、分享（复制当前链接）。
• 扩展项：「操作下拉菜单组」中可添加 在 ChatGPT 中打开、在 Claude 中打开、自定义（自定义 SVG 图标、标题与链接）。

主题与外观

• 明暗主题：默认跟随系统，支持手动切换并记忆（localStorage: mdocs-theme）。
• 昼 / 夜 Logo：页眉与页脚可分别配置浅色、深色 Logo，切换主题时自动替换。
• 主题色：可设置全局主色；留空或为黑白灰时自动按明暗主题使用黑 / 白。
• 全局样式：字体大小、全局圆角、页面背景图或背景色。
• 背景图遮罩：快速开始卡片支持开启色彩遮罩并自定义遮罩颜色。
• 宽度体系：由 --mdocs-width-content（1080px）与 --mdocs-width-page（1400px）两个 CSS 变量统一控制。

页眉与页脚

• 页眉：站点 Logo / 名称、左侧导航按钮组（最多 3 个）、主菜单下拉、搜索入口（需 PluginSearchWidget，支持 ⌘K）、自定义图标按钮组（最多 6 个）、明暗切换、用户菜单（登录 / 用户中心 / 控制台 / 退出）。
• 页脚：多列菜单（最多 4 个 Halo 菜单）、独立页脚 Logo、站点名称、版权信息、ICP 备案与公安联网备案。

首页模块（可拖拽排序）

模块	类型值	说明
主视觉	hero-carousel	标题 / 副标题 / 主次按钮 / 安装方式标签 / 轮播图（自动播放、拖拽切换、导航点）
快速开始	quick-start	主推大卡 + 侧边卡片，支持背景图与色彩遮罩
卡片模块	cards	type1 背景图样式 / type3 图标简洁样式
文章分类	ocean-categories	按分类生成卡片，支持主色、封面与自定义底部代码
菜单模块	ocean-menu	展示指定菜单的前 4 个一级菜单项
推荐文章	ocean-posts	按标签或分类取前 6 篇
Docsme 文档项目	plugin-docsme-module	可自动读取插件归档卡片或手动添加
MiniDocs 知识库	plugin-minidocs-module	可自动读取插件归档卡片或手动添加

自定义模板

模板名	文件	适用位置
文档	post_documentation.html	文章 → 新建
docsme-docs	docsme-docs.html	页面 → 新建
minidocs-docs	minidocs-docs.html	页面 → 新建

其他

• 响应式布局，移动端提供抽屉式目录与汉堡菜单。
• 使用语义化标签与 aria-* 属性，兼顾无障碍与 SEO 基础。
• 全站 CSS 变量驱动的设计令牌，便于二次定制。

环境要求

依赖	版本 / 说明
Halo	>= 2.25.0
Node.js	^20.19.0 或 >= 22.12.0（仅本地构建需要）
pnpm	10.x（package.json 已声明 packageManager: pnpm@10.33.0）

可选插件（未安装时对应入口自动隐藏，不影响主题其它功能）：

插件	标识	作用
Docsme	plugin-docsme	文档中心 / 项目目录 / 文档详情适配
MiniDocs	halo-plugin-minidocs	知识库归档与内嵌阅读
搜索组件	PluginSearchWidget	页眉搜索入口与 ⌘K 快捷键

使用须知

• 本项目为构建型主题：请修改 src/ 下的模板与资源后执行 pnpm build，不要直接编辑 templates/ 下的生成文件。
• 后台「外观 → 主题」中修改 theme.yaml 后，需点击「重载主题配置」才会生效。
• 主题目录名必须为 theme-mdocs，需与 theme.yaml 的 metadata.name 保持一致。
• 主题设置中所有涉及跳转的选项默认值为空，留空时不会输出无效链接；备案号留空时备案栏整体不显示。
• 默认预置了演示模块，正式建站时请替换「快速开始」「卡片模块」中的示例文案与示例图片。

隐私

• 主题不采集、不上传任何站点或访问者数据；仅在浏览器本地使用 localStorage 记忆明暗主题偏好（键名 mdocs-theme）。
• 页面字体使用访问者系统自带字体栈，不下载、不内嵌第三方字体。

许可

• 以 MIT 许可发布，许可证全文见根目录 LICENSE，主题元信息见 theme.yaml 的 spec.license。

---

后续版本

新版本发布时，在本文件顶部按同样格式追加一节，并同步更新 theme.yaml 的 spec.version 与 README.md 中的版本徽章与兼容性表格。