1.2.0

发布日期：2026-10-03
主题包：dist/theme-mdocs-1.2.0.zip
适用 Halo：>= 2.25.0

小版本更新：参考语雀（Yuque）公共页面的版式，为 Docsme、MiniDocs 两个插件页面补齐页面级自定义能力，并修复首页模板编译产物被截断的问题。

新增

插件页面英雄块

参考语雀公共页面的头部区，为两个插件页面各新增一组英雄块设置：

• 新增 启用英雄块 开关，默认关闭；开启后在页面顶部渲染英雄块，并展开下方 5 项子设置，关闭时不输出任何结构。

• 子设置项：

  子设置项	默认值	说明
  英雄块背景图	空	通栏铺满页面顶部，自动叠加半透明遮罩保证文字可读
  英雄块标题	空	与 Logo 同一行显示；留空时回退为当前页面标题
  英雄块 Logo	空	与标题同一行，显示在标题左侧
  英雄块描述	空	标题下方的说明文字
  搜索框占位文字	请输入	回车跳转 /search?keyword=，需安装 PluginSearchWidget 搜索插件

• 未安装 PluginSearchWidget 时不渲染搜索框，英雄块其余部分正常显示。

插件页面描述模块

接着英雄块下方，为两个插件页面各新增一组描述设置：

• 新增 启用描述模块 开关，默认关闭；开启后渲染描述列表，关闭时不输出任何结构。
• 描述内容以 列表形式 配置，array 组件限制 最多 3 条（max: 3），支持拖拽排序、增删；每条包含 标题 与 文本内容 两个字段。
• 文本内容支持换行与简单 HTML（链接、加粗等），默认预置 3 条占位文案（快速上手 / 常用文档 / 了解我们），可直接修改或删除，删空后该模块不再输出。
• 前端按三列排布：960px 以下两列，720px 以下单列。

插件页面显示页眉开关

• 两个插件页面分组各新增 显示页眉 开关，默认开启。
• 关闭后该插件页面顶部不再显示站点页眉，首页、文档页等其他页面不受影响。

仅显示页面模块

• 两个插件页面分组各新增 仅显示页面模块 开关，默认关闭。
• 关闭时页面自上而下渲染：英雄块 → 描述模块 → 页面模块 → 文档列表（Docsme 项目列表 / MiniDocs 知识库列表），与 1.1.0 行为一致。
• 开启后不再渲染文档列表，页面内容由页面模块决定。
• MiniDocs 的知识库阅读器挂载点 #minidocs-viewer-host 已移出该判断条件，?kb= 直达阅读不受影响。

优化

• 两个插件页面沿用首页的公共模块片段 src/partials/home-modules.html（编译内联到各模板），首页与插件页面共用同一份模块实现。
• 条件设置项统一使用 $get(字段 id).value 形式的联动表达式，开关切换后子设置项即时显隐，无需先保存。
• 全部新增设置项均补齐默认值（含 descriptions 数组的 3 条占位文案），重载主题配置后即可直接使用。

修复

• 修复首页模板重构后 templates/index.html 编译产物缺失闭合标签、只剩首行的问题（.homepage-container 未闭合导致后续内容被丢弃）。

1.1.0

发布日期：2026-09-15
主题包：dist/theme-mdocs-1.1.0.zip
适用 Halo：>= 2.25.0

小版本更新：补齐错误页体系，补上归档 / 标签 / 分类列表页与 Markdown 正文缺失的排版，并新增大屏适配。

新增

错误页

• 按状态码定制错误页，模板位于 templates/error/，Halo 按「精确状态码 → 4xx / 5xx 类别 → error.html」的顺序匹配：

  模板	触发	标题
  404.html	404	页面走丢了
  500.html	500	服务出了点问题
  4xx.html	401 / 403 / 405 / 429 等	请求无法完成
  5xx.html	502 / 503 / 504 等	服务出了点问题
  error.html	最终兜底	按状态码自动选择 4xx / 5xx 文案

• 五个页面共用 error-page.html 片段，保留站点页眉页脚、明暗主题与主题色，不会出现样式裸奔。

• 操作区：返回首页、返回上一页、浏览归档、搜索文档（需 PluginSearchWidget）、重新加载（仅 5xx）。

• 优先展示 error.status / error.detail，字段为空时回退到内置文案，不会因为缺字段而报错。

列表页样式

• 归档、标签、作者、普通分类页此前直接沿用浏览器默认样式，现补齐：页面大标题、归档年月分组、文章条目分隔线与悬停态、文章标题与元信息、分类 / 标签标签块、分页导航。
• 所有选择器限定在 .page-wrap 作用域内，首页、文档页、插件页的表现不受影响。

正文排版

• 补齐有序 / 无序列表（含嵌套）、分隔线、图片与图注、定义列表的排版规则。
• 表格沿用原有的横向滚动保护，未做改动。

大屏适配

• >= 1600px：左侧导航 320px、右侧 TOC 280px、插件卡片网格 5 列。
• >= 2200px：左侧导航 360px、右侧 TOC 320px、插件卡片网格 6 列。
• 1600px 以下的表现与 1.0.0 完全一致；首页内容与页脚的定宽由原来的 1080px 放宽到 1280px。

优化

• 文档页、文章页、分类页等 6 处 theme.config.docs.X 改为安全导航 docs?.X，未配置文档设置时不再出现渲染异常。
• 错误页操作区中 <button> 与 <a> 的字体、光标表现保持一致。
• 页脚公安联网备案去掉图标，仅保留备案号文字，与 ICP 备案保持一致的排版。
• 补全开源元信息：theme.yaml 增加仓库地址（https://github.com/KetchupKeeper/theme-mdocs）、Issues 地址（/issues）、作者主页，许可证链接指向仓库内的 LICENSE，主题描述扩充为完整能力清单；README 补充仓库、许可与反馈入口、贡献指引，并修正页脚宽度描述。
• 版本说明改为按版本号拆分：每个版本一个文件，统一放在 docs/versions/ 下（如 docs/versions/1.1.0.md），根目录的 CHANGELOG.md 仅作索引。

修复

• 标签页 /tags 返回 500：tags 是列表而非分页对象，改为直接遍历，并移除无效的分页块。

版本说明

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