Obsidian 插件提交指南 (VitePress Theme 插件实战版) ​

使用 Obsidian 后，发现不能支持 Vitepress 的很多特性，也缺少相关插件，于是自己捣鼓了一个并提交到 Obsidian 官方插件库，特此记录

1. 准备工作：本地配置校对 (Local Setup) ​

在发起任何提交前，请确保你的 manifest.json 和 package.json 完全符合以下规范：

• Plugin ID 规范:
  • ❌ 禁止包含 "obsidian" 字眼。
  • ✅ 建议简洁、描述性强，如 vitepress-theme。
• Description 一致性:
  • manifest.json、package.json 以及 community-plugins.json 中的 description 字段必须字字一致（包括标点符号）。
• 字段完整性:
  • author、authorUrl、repository 等字段建议尽可能补全，这有助于增加审核员的信任度。

以下是我的配置：

{
  "id": "vitepress-theme",
  "name": "VitePress Theme",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "VitePress-style theme with custom containers, enhanced code blocks, and modern typography.",
  "author": "weizwz",
  "authorUrl": "https://github.com/weizwz",
  "fundingUrl": "",
  "isDesktopOnly": false
}

2. GitHub Release 发布规范 (The Release) ​

这是自动化审计最容易报错的环节。

• Tag 名称: 必须是纯数字版本号，例如 1.0.0。
  • ❌ 禁止使用 v1.0.0（这是最常见的报错原因）。
• Release Assets:
  • 必须包含：main.js、manifest.json。
  • 可选包含：styles.css（如果你的 CSS 是外置的）。
  • 所有文件必须是散装上传，不能只在 Source code (zip) 里。

如图所示，main.js、manifest.json 为手动上传，其余文件为自动生成。

3. 提交至 obsidian-releases (The Pull Request) ​

第一步：同步上游 ​

1. Fork obsidianmd/obsidian-releases。
2. 如果你之前已经 Fork 过，则在你 Fork 的仓库主页执行 Sync Fork 以确保你是从最新的主分支开始修改。

第二步：编辑 community-plugins.json ​

1. 将你的插件信息作为一个新的对象添加到数组的 最末尾。
2. 插入信息请和你的 manifest.json 中的内容保持一致。
3. 严禁插入到中间任何位置，否则自动化审计会判定失败。
4. 编辑完成后提交到你 Fork 的仓库。

第三步：发起 PR ​

1. 到 obsidian 官方插件推送库 New pull request。

2. 选择 Compare across forks: 确保 Base 是 obsidianmd:master，Compare 是你第二步中已提交插件配置的仓库和分支。

3. 使用官方模板: - 点击 Preview 选项卡。- 选择 [Community Plugin](?template=plugin.md) 链接。- 勾选所有 Checklist 项（不要删除任何模板标题）。

   提示

   查看 官方模版链接，直接复制模板，填写对应内容也可。plugin.md 是插件模块，theme.md 是主题模块

提交成功的示例如下，还要等待自动化代码检查。右侧的 Changes requested 表明自动化代码检查后提出了相关意见，需要修改。

4. 自动化审计报错排查 (Audit Troubleshooting) ​

如果机器人 GitHub Actions 扫描出红色 ❌，请对比以下常见原因：

• ID Naming: "Please don't use the word obsidian in the plugin ID"。
• Description Mismatch: "The description in this PR is not the same as the one in your repo"。
• Tag Not Found: "Unable to find a release with the tag 1.0.0"。
• Entry Position: "The newly added entry is not at the end"。

5. 官方人工审核关注点 (Reviewer Focus) ​

一旦通过自动化审计，审核员会人工检查你的代码。他们通常关注：

• 性能:
  • 是否有长期运行的定时器（建议改用 MutationObserver）。
  • DOM 扫描是否有合理的防抖处理。
• 安全性:
  • 禁止使用 eval() 或动态注入具有安全风险的脚本。
  • 注入用户文字时，务必使用 textContent 而非 innerHTML，以防止 XSS。
• 依赖管理:
  • 尽量减少大型重型库的依赖。
• 稳定性:
  • 针对复杂渲染场景（如 HTML 预热拦截等），是否具备补救策略（Source-Recovery）。

6. 让 AI 根据审核意见修改 ​

如果审核后有问题，通常类似这样

我们在审核意见右侧，复制 markdown 内容（为什么这样做，因为[1] [2]等带链接，指向了项目具体文件，复制 markdown 能体现出文件路径），投喂给 AI，让它帮我们列举具体的修改任务。

我的 Obsidian 插件提交后，有一些审核意见。请根据意见安排修改计划。
意见中的 github 链接对应项目中文件目录，比如：[\[1\]](https://github.com/weizwz/obsidian-vitepress/blob/628fec240e499601f26d967b1159855ed0ad5352/src/features/codeEnhancer.ts#L159-L159) 对应 src/features/codeEnhancer.ts#L159-L159，L159就代表 159 行

xxx，此处粘贴 Markdown 审核内容

AI 会给你列出详细的修改计划，比如：

然后根据计划自行或者让 AI 帮你修改即可。修改提交后，切记不要创建新 PR，Obsidian 会定期自动扫描代码，有修改后会自动监测到并给你评审意见。

修改完成后，如果自动化扫描没有问题，PR 状态会变成 PR Ready for review，这时候我们等待人工审核即可。

7. 合并后的操作 ​

1. 自动上架: 审核员点击 Merge 后，你的插件通常会在几个小时内出现在 Obsidian 插件商店中。
2. 版本更新: 以后升级插件，只需在你自己的仓库发布新的 Release（Tag 依然需遵循 x.y.z 格式），Obsidain 客户端会自动检测并提醒用户更新。

最后祝愿你的插件成功提交并开启社区之旅！ 🚀