Obsidian 与 Astro 内容发布系统

目标

在保留私有知识库编辑体验的同时，只把明确批准的内容同步到公开网站，并让本地校验与线上部署保持可重复。

本人职责

• 设计私有知识库与公开网站之间的目录边界和发布白名单。
• 实现内容校验、语法转换、资源同步、生成清单和公开路由检查。
• 建立本地与 GitHub Actions 共用的构建、浏览器、无障碍和性能门禁。

系统架构

• Obsidian 知识库是唯一编辑源。
• 40_Publish 是公开内容白名单，不采用“全部发布后再排除私有文件”的方式。
• 公开网站使用 Astro 与 Starlight；文章、项目、固定页面和资源由同步工具生成。
• GitHub Actions 只读取公开网站仓库，完成公开仓库检查、静态构建和 GitHub Pages 部署。

硬件与软件环境

• **编辑与本地验证：**Windows 工作站、Obsidian、Node.js。
• **网站：**Astro、Starlight、TypeScript、原生 JavaScript。
• **持续集成：**GitHub Actions、GitHub Pages、Playwright、axe、Lighthouse。

关键实现

• 校验 Front Matter、类型目录、状态、可见性、slug 和路由冲突。
• 转换常用 Obsidian Wikilink、图片嵌入和 Callout 语法。
• 在发布前检查敏感信息、附件、内部链接、必备路由和旧 URL 重定向。
• 使用生成内容清单记录源文件、输出文件、路由和哈希，避免覆盖非生成文件。

问题与排查

• 将私有知识库与公开网站拆分为两个 Git 仓库，避免公开构建读取私有源文件。
• 对生成输出记录源、目标、路由和哈希，防止同步工具覆盖手写文件或遗留陈旧文件。
• 使用必要路由、站内链接和旧 URL 映射检查，降低迁移后的断链风险。

测试方法

• 在同步前校验 Front Matter、状态、可见性、slug、附件和内部链接。
• 扫描准备公开的源文件和资源，阻止敏感信息进入网站仓库。
• 同步后校验生成标记、清单所有权和哈希。
• 对静态站点运行类型检查、构建、链接、路由、重定向、浏览器、无障碍和 Lighthouse 检查。

验证结果

完整发布命令会依次执行内容校验、敏感信息扫描、同步、生成内容完整性检查、单元测试、Astro 类型检查、生产构建、链接检查、路由检查和重定向检查。任一步失败都会阻止后续发布。

当前限制

• 内容事实和视觉材料仍需要人工编辑审核，自动化检查不能代替内容责任。
• 知识成熟度与跨内容关联尚未形成统一公开元数据。

下一步

• 持续补充经过审核的真实工程项目和验证素材。
• 保持 README、设计 QA、生成清单和生产部署状态同步。

Publishing lab

从私人笔记，到公开知识。

点击两个状态，查看同一份 Markdown 如何经过白名单检查，进入 Astro 与 Starlight。

私有编辑公开构建

01

Obsidian 中持续整理

内容先留在私有知识库；只有进入 40_Publish、标记为 public 且状态就绪的 Markdown 才能继续。

visibility: public · status: ready