源蝶文档 1.0.0 发布

Mon, 14 Sep 2026 09:48:03 GMT

版本说明

本文档记录 源蝶文档（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 中的版本徽章与兼容性表格。

查看版本详情

Halo - 强大易用的开源建站工具 | 应用市场 | 源蝶文档 | 版本发布