Super Productivity Wiki 贡献实战：使用 Obsidian 配置与 Markdown 规范写作指南-港品优选

Super Productivity Wiki 贡献实战：使用 Obsidian 配置与 Markdown 规范写作指南

【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity

本文是 Super Productivity 开源仓库中 Wiki 贡献文档的完整实战解读：说明如何将 Obsidian 配置成与仓库 Wiki 标准兼容的编辑器，并深入讲解仓库的 CI 校验机制、Markdown 风格规范与提交前检查命令。读完本文，你将掌握一套可直接落地的 Obsidian 配置方案，并理解为何这些设置能够保证所写文档通过仓库的自动化检查、顺利合并进docs/wiki。

背景：Wiki 与仓库的关系

Super Productivity 的 Wiki 页面并非独立仓库，而是以普通 Markdown 文件的形式存放在仓库的docs/wiki目录中。仓库通过 wiki-sync.yml 这一 GitHub Actions 工作流，在每次 push 到master/main分支且docs/wiki/**有变更时，用rsync以"硬镜像"方式（--delete删除远端多余文件）将docs/wiki同步到 GitHub Wiki 仓库。

这意味着：代码仓库是唯一的事实来源（source of truth），所有贡献都应在docs/wiki内完成。因此，任何用于编辑该目录的工具——尤其是 Obsidian——都必须遵守仓库的 Markdown 规范，否则产出的文档无法通过 CI 检查，也无法在 GitHub 端正确渲染。

Obsidian 功能强大但默认配置会生成与仓库标准不一致的 Markdown，这正是本文要解决的配置问题。整体配置思路围绕两份核心文档展开：0.01-Style-Guide（风格规范）与 0.00-Wiki-Structure-and-Organization（结构与组织规范）。

第一步：Git 集成（仓库侧准备）

1. 以`docs/wiki`为 Vault 根目录

打开 Obsidian 时，必须新建一个 Vault，其根目录指向super-productivity/docs/wiki。这样新建的笔记会出现在super-productivity/docs/wiki/note.md，即笔记必须保持扁平存放——不创建嵌套子目录。

这一要求源于 0.01-Style-Guide 中说明的原因：GitHub Wiki 会折叠不同子目录中的同名笔记（例如Dir1/note.md与Dir2/note.md会被合并成一篇，另一篇变得无法访问），因此所有笔记都应扁平存放在docs/wiki根下，只有图片等资源可以放入assets子目录：

vault/ ├─ 1.01-First-Steps.md ├─ 2.09-Configure-Sync-Backend.md │ ├─ assets/ │ ├─ 1.01-First-Steps-start-time-tracking.png │ ├─ diagrams/ │ ├─ flow.png

2. 阻止 Obsidian 数据泄漏进仓库

Obsidian 会在 Vault 根目录生成.obsidian配置目录。为避免它被提交进仓库，使用 Git 的本地排除机制（仅本机生效，不会写入.gitignore影响他人）：

echo ".obsidian" >> .git/info/exclude

3. 提交前保证 Markdown 通过 lint

每次 commit 前都应确保 Markdown 通过 lint 检查，具体 lint 规则见风格指南的 Linting 一节。最简单可靠的方式是配置 Git 的 pre-commit 钩子：

cat > .git/hooks/pre-commit <<'EOF' #!/bin/sh set -eu pymarkdownlnt --disable-rules line-length scan "docs/wiki" EOF chmod +x .git/hooks/pre-commit

注意：上述钩子中的chmod +x仅作用于你本地.git/hooks/内的钩子文件，用于确保每次提交前自动触发 lint。仓库内已有的docs/wiki页面不受影响。

4. 不要使用 Obsidian 的 Git 插件

Obsidian 的社区 Git 插件虽然方便，但其提交方式、文件操作与仓库的 CI 流程和上述排除机制并不完全兼容，文档明确要求不要启用该插件。提交管理统一交给仓库侧的 Git 流程完成。

第二步：Obsidian 设置（与默认值的差异）

编辑器（Editor）设置

设置项	推荐值	原因
Strict Line Lengths（严格行宽）	开启	预览模式下能正确显示 GitHub 如何渲染单行空格；可以通过在行尾追加两个空格创建"单行换行"（soft break）
Default Editing Mode（默认编辑模式）	Source Mode（源码模式）	推荐在一个窗格用源码模式编辑、另一个窗格开启实时预览联动，可显著减少 Linter 会报告的问题
Show Line Numbers（显示行号）	开启	便于看清行尾空格数量
Indent using Tabs（使用 Tab 缩进）	关闭	关闭后 Tab 键被硬编码为 4 个空格；但仓库规范要求只用 2 个空格缩进（尤其嵌套列表），因此需要手动输入 2 个空格

其中缩进规范来自 0.01-Style-Guide 的 Indenting 一节：禁用 Tab，一律 2 空格。这是与绝大多数 Markdown 工具默认 4 空格缩进差异最大的点，嵌套列表场景尤其容易踩坑。

文件与链接（Files and Links）设置

设置项	推荐值	原因
Default Location for New Attachments	指定为`./assets`目录	图片统一落到`docs/wiki/assets`，保持 Wiki 根目录整洁（对应仓库中 assets 目录的实际组织方式）
New Link Format	Path from Vault（相对 Vault 的路径）	防止出现重名笔记造成的链接歧义
Automatically Update Internal Links	开启	文件重命名时自动更新引用，减少 Broken Links 插件报错

第三步：推荐插件及配置

Broken Links

提交前运行一次，扫描并修复文档中的断链。GitHub Wiki 对路径和命名的处理很特殊，很多链接问题只有这个插件能提前暴露。

Paste image rename

使用默认设置即可。它的价值在于保证图片命名一致（粘贴图片后自动按规则重命名），这符合仓库中图片命名风格（如1.01-First-Steps-start-time-tracking.png的数字-章节-动作模式）。

Linter（可选）

Obsidian 的 Linter 插件属于可选增强项。如果使用，必须注意：

将其配置与 0.01-Style-Guide 保持一致；
以仓库的 CI 检查为权威，不要直接照搬网上复制的 Obsidian 配置——CI 规则会持续演进，复制配置会逐渐漂移失效。

仓库 CI 的权威规则就是 wiki-sync.yml 中执行的pymarkdownlnt --disable-rules line-length,no-inline-html scan "docs/wiki"。本地若有 Python 环境，可通过pipx install pymarkdownlnt（Arch 系）或其他包管理器安装后自行复跑。

Safe Filename Linter

将所有选项设置为"Empty String"（空字符串），并在提交前对所有文件运行。这与风格指南中 Spaces and Dashes 一节的要求吻合：文件名中的空格一律替换为短横线，避免出现API Reference.md与API-Reference.md这类 GitHub 无法区分的重名冲突。

第四步：理解 CI 校验，让配置有的放矢

Obsidian 配置的每个细节背后都是仓库 CI 的具体规则。理解这些规则有助于你判断插件设置是否正确。

1. Markdown 语法 lint（pymarkdownlnt）

wiki-sync.yml 的lintjob 在 Ubuntu 上安装pymarkdownlnt后扫描整个docs/wiki：

pymarkdownlnt \ --disable-rules line-length,no-inline-html \ scan "docs/wiki"

两个被禁用的规则也值得注意：line-length（行宽）与no-inline-html（行内 HTML）被显式关闭，即行长度不限、允许使用行内 HTML——这两条放宽后，Obsidian 的 Strict Line Lengths 设置和仓库内偶尔的 HTML 注释（如风格指南中的）才不会误报。

此外还有一个细节规则MD041（文件首行应为一级标题）。如果某个笔记不需要 H1，可以在文件第一行（前面不留空行）写入：

<!-- pyml disable md041 -->

该 pragma 会在解析前被剥离，不影响渲染，只对该文件豁免 MD041。若要整库关闭 H1 要求，则把md041加入 CI 的--disable-rules列表即可。

2. 本地链接与锚点校验（check-doc-links）

仓库提供了零第三方依赖的链接检查器 check-doc-links.js，由 package.json 中的脚本暴露：

npm run docs:check-links

该工具会验证 Markdown 链接、HTMLhref/src属性、图片与 wiki 链接，并且拒绝 wiki 链接中的别名语法（如[[9.Test-Note|Test Note]]），因为 GitHub 对这类语法在此仓库中渲染不正确——这正是 Obsidian 里"New Link Format 选 Path from Vault"的原因。工具还额外扫描源码注释中对docs/**路径的引用（checkSourceDocRefs），防止文档被删除后留下悬空引用。

3. 提交前完整检查命令

根据 0.02-Wiki-QA-and-Maintenance，提交 PR 前运行：

npm run docs:check-links pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wiki

pymarkdownlnt本地可选但 CI 必装；链接检查器无任何第三方依赖。外部 URL 不会被自动爬取校验（网络抖动不适合作为 PR 门槛），因此新增或修改外部链接时应人工打开确认，优先使用稳定的一手来源。

第五步：写作风格要点（配合 Obsidian 使用）

链接写法

风格指南要求使用 Wiki 风格链接（[[...]]）而非冗长的 Markdown 链接，GitHub 与 Obsidian 的差异仅在于 GitHub 不需要!前缀。仓库内两种写法均合法：

[[image-at-root.png]] # 根目录图片 [[images/image.png]] # 嵌套目录图片

严禁使用别名语法（[[note|显示名]]），它会渲染为无法解析的路径，并被check-doc-links.js直接判为错误。

锚点（Anchor）使用节制

标题锚点在同一篇笔记内也是扁平的：空格变短横线、大写变小写。风格指南建议谨慎使用深层锚点，尽量保持笔记篇幅精炼，从根源上避免深嵌套引用。

章节归属

新增或更新页面时，按照 0.00-Wiki-Structure-and-Organization 的规则选择合适分区（0-Meta、1-Quickstarts、2-How-to、3-Reference、4-Concepts），文件名带编号前缀以保持 GitHub Wiki 内的分组顺序，且不要随意重命名（现有链接和书签依赖文件名）。新页面还应从对应的分区索引页（如 2.00-How_To）与 _Sidebar 加入入口链接。

总结

将 Obsidian 配置为 Wiki 贡献编辑器并不复杂，核心是四点：Vault 根目录指向docs/wiki、关闭 Tab 缩进并坚持 2 空格、附件落位assets、提交前过一遍插件与 CI 检查。这些设置看似琐碎，实际每一条都对应着 GitHub Wiki 的路径折叠机制、重名吞并风险与pymarkdownlnt的具体规则。把 wiki-sync.yml 与 check-doc-links.js 的校验逻辑作为权威基准，Obsidian 就能成为一套与仓库 CI 完全对齐、可长期稳定维护 Wiki 内容的编辑环境。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析