MiniDocs 知识库使用教程

MiniDocs 是 Halo 2.x 的轻量知识库插件，用于搭建团队或个人知识库。它支持多知识库管理、文档树层级、Markdown 可视化编辑、分类标签、发布/草稿、权限控制与外链分享，并通过 minidocsFinder Finder API 与匿名公共 REST API 将内容暴露给第三方主题，方便搭建用户侧的文档站点。

目标平台：Halo >= 2.26.0

管理端入口：Console 左侧菜单的「知识库」（如 你的域名/console/minidocs）

一、登录并进入知识库

1. 使用管理员（或拥有「知识库查看／知识库管理」角色的）账号登录 Halo Console：你的域名/console。

2. 在左侧「内容」分组中找到「知识库」菜单并点击，进入知识库管理主页。

主页顶部以统计卡片展示总览（知识库总数、公开数量、私有数量、文档总数），下方是搜索、标签筛选、排序与视图切换，再往下是知识库卡片网格。每张卡片展示封面、名称、标签、权限标签（公开/私有/团队）、文档数、浏览量、点赞数与最后更新时间，卡片右下角提供「进入 分享 编辑 / 删除」等操作。

二、新建知识库

点击右上角「新建知识库」按钮，弹出新建表单：

填写后点击「保存」即可建库。创建成功后可继续在卡片上点「进入」维护文档，或点「编辑」完善公开性、成员等更多配置（见第五节）。

创建者会自动写入 creatorName，并默认成为该库的可访问者。

三、文档管理

进入某个知识库后，会看到 左侧文档目录树 + 右侧编辑区 的双面板界面：

• 工具栏：支持「批量导入 Markdown」「新建文档」「全部展开/折叠」「搜索文档标题」，并展示知识库信息（文档数量、权限、创建人）。

• 文档树：支持用「文件夹↔文档」组织层级结构，形成如 插件指南 → 详细教程 的父子层级。

• 右侧编辑区：未选择文档时显示空状态；选中左侧某篇文档后即进入编辑器。

四、编辑文档（Markdown 可视化编辑器）

在文档树中点击任意文档，右侧即打开基于 Cherry Markdown 的编辑器：

功能区说明：

• 预览 / 编辑：右上角切换「编辑&预览（左右分屏实时预览）」与「纯预览」两种模型；编辑时支持标题、列表、代码块（Prism 高亮）、公式（KaTeX）、Mermaid 图表等语法。

• 工具栏按钮：保存、发布/取消发布、移动到（调整文档归属）、复制、删除、设置等。

对已发布文档点「保存」即更新并重新发布（自动刷新 publishTime）；草稿状态点「发布」才对外可见。

• 右侧浮动目录（TOC）：根据文档标题自动生成锚点导航，方便长文跳转。

• 底部状态栏：字数、行数、作者、创建/更新时间等元信息，以及「回到顶部」按钮。

保存时会把 Markdown 原文写入 spec.raw，同时由编辑器同步生成 HTML 存入 spec.content，前台阅读页据此渲染正文。

五、配置知识库（权限与成员）

在知识库列表页点击卡片上的「编辑」（铅笔）图标，即可修改知识库信息：

除名称、链接别名、描述、封面、优先级外，还包含两项关键配置：

• 标签：输入后回车添加，多个标签可供检索与归类。

• 成员（私有知识库可访问者）：仅当「公开可见」关闭（私有）时生效，可勾选允许访问该私有库的用户；开启公开可见后无需设置成员。

• 公开可见：开关。开启后该库对所有人生效（含未登录访客，具体还受插件设置的「允许未登录用户阅读公开知识库」约束）；关闭则仅创建者、成员及管理者可见。

保存时仅更新用户可编辑字段（显示名、别名、描述、封面、优先级、标签、成员、公开可见），系统字段（访问量、点赞、创建人等）会被保留。

六、外链分享

MiniDocs 支持把知识库通过一条外链分发给任意访客。点击卡片右下角的分享图标（绿色节点样式）打开分享弹窗：

• 开启外链分享：总开关。开启后任何人持外链即可查看，不受知识库公开/私有权限约束（访问私有库也不需登录，仅受分享自身限制）。

• 访问密码：留空则无密码直进；填写后必须输入密码才能进入。

• 外链有效期：永久 7 天 30 天 / 90 天，到期后外链自动失效。

• 分享外链：保存后生成 你的域名/docs/share/{token}，点击「复制链接」分发给访客。

机制说明：每个知识库对应一条固定外链；关闭再开启时 token 不变、链接不变化。密码校验通过后，服务端下发 HttpOnly Cookie，有效期内无需重复输入。收藏/点赞等互动同样被记录。

七、前台阅读页（访客视角）

把分享外链（或前台公开路由）分发给访客后，他们在浏览器打开即可看到知识库阅读页：

• 左侧：知识库标题、文档统计、「共 N 篇」、搜索框与文档树目录（支持展开层级并高亮当前文档）。

• 中间：完整渲染的 Markdown 正文（标题、列表、代码块、提示框等），顶部提供收藏/点赞、分享、浏览量统计。

• 右侧：根据标题生成的浮动目录导航。

• 底部：面包屑、字数行数、作者与创建/更新时间。

前台阅读页遵循同样的可见性规则：对外（列表、文档树、阅读页）只展示 published（已发布）的文档；草稿仅创建者/成员/管理者可在 Console 中看到。

八、导入与导出

• 批量导入 Markdown：在文档管理页工具栏点「批量导入 Markdown」，上传 .md 文件即可（可指定父级目录）。导入的文档只写入原始 Markdown，正文由前端用同一套 Cherry 渲染管线补齐。

• 导出：单篇文档可导出为 Markdown；也可通过「导出」批量导出整个知识库为 ZIP。该能力受插件设置「允许导出文档（Markdown）」约束——关闭时两者均返回 403，且批量导出只包含当前用户有权限的库。

知识库导出与导入 ZIP

在知识库主页点「导入知识库」上传的 ZIP，仅限由本插件导出的知识库包。导出与导入使用固定的包结构：

{知识库名称}/
├── config.json          # 知识库元数据配置 + 文档清单（导入依据）
└── docs/
    ├── {slug}.md        # 文档 Markdown 原文
    └── ...

其中 config.json 记录了知识库的名称、描述、封面、标签、公开性，以及每个文档的 slug、标题、父子关系、作者与时间信息。导入时会通过每个知识库目录下的 config.json 识别并还原知识库；没有 config.json 的目录会被忽略。

使用与注意事项：

• 本地修订后导回：你可以在本地用任意编辑器修订 docs/*.md 的正文内容后，把 ZIP 导回重新导入。请务必保留 ZIP 包根目录下的 config.json 配置文件，不要删除——它还原了文档清单、slug 与父子层级，删除后该知识库将无法被正确识别与还原。

• 跨站迁移：在旧网站用本插件导出知识库为 ZIP，再在新网站用本插件「导入知识库」导入即可完成迁移，知识库结构、文档层级与元信息会一并还原。同名知识库默认采用「安全覆盖」策略（先建新 → 验证完整性 → 删旧 → 恢复 slug），失败自动回滚、原数据不受影响。

• 导入的文档默认均处于草稿状态，可在知识库内「一键发布」后对外可见。

九、角色与权限模型（面向管理员的要点）

权限分两层叠加生效：

• Halo 角色模板决定谁能在 Console 操作知识库：

  • 知识库查看：知识库与文档的 get、list（读取）。

  • 知识库管理：知识库与文档的 create、update、delete 等写操作，并自动依赖「知识库查看」。

  • 匿名角色：自动聚合「未登录用户阅读公开库」所需的 get、list 权限。
    

• 资源级访问控制决定谁能读某个具体知识库/文档：

  • 公开库：任何人可见（受「允许未登录用户阅读公开知识库」开关约束）。

  • 私有库：仅创建者、成员、具备管理权限的用户可见，其余请求在 Console 返回 403、在该接口/Finder 返回 404。

只要分配了「知识库管理」角色或属于超级管理员，即为知识库管理者，可访问全部（含私有）知识库。

十、常用用法建议

1. 个人文档库：把知识库设为私有，仅自己维护，定期用「一键发布」把草稿批量发布对外。

2. 团队 Wiki：建议一个主题一个知识库并赋予成员，保持文档树清晰、层级合理。

3. 对外文档站：设为「公开 + 允许未登录阅读」，再结合 minidocsFinder / 公共 REST API 在主题中渲染知识库列表与文档内容。

4. 临时对外分享：用「外链分享 + 访问密码 + 有效期」控制分享范围，避免泄露私有内容。

5. 内容迁移：用「批量导入 Markdown」快速搭建内容物资，用 ZIP 导出做备份或迁移。

本教程面向日常使用场景编写，更多实现细节可参考：

• 开发文档

• 主题 API 文档

• REST API 文档