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.png2. 阻止 Obsidian 数据泄漏进仓库Obsidian 会在 Vault 根目录生成.obsidian配置目录。为避免它被提交进仓库使用 Git 的本地排除机制仅本机生效不会写入.gitignore影响他人echo .obsidian .git/info/exclude3. 提交前保证 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 breakDefault 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 FormatPath 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 pymarkdownlntArch 系或其他包管理器安装后自行复跑。Safe Filename Linter将所有选项设置为Empty String空字符串并在提交前对所有文件运行。这与风格指南中 Spaces and Dashes 一节 的要求吻合文件名中的空格一律替换为短横线避免出现API Reference.md与API-Reference.md这类 GitHub 无法区分的重名冲突。第四步理解 CI 校验让配置有的放矢Obsidian 配置的每个细节背后都是仓库 CI 的具体规则。理解这些规则有助于你判断插件设置是否正确。1. Markdown 语法 lintpymarkdownlntwiki-sync.yml 的lintjob 在 Ubuntu 上安装pymarkdownlnt后扫描整个docs/wikipymarkdownlnt \ --disable-rules line-length,no-inline-html \ scan docs/wiki两个被禁用的规则也值得注意line-length行宽与no-inline-html行内 HTML被显式关闭即行长度不限、允许使用行内 HTML——这两条放宽后Obsidian 的 Strict Line Lengths 设置和仓库内偶尔的 HTML 注释如风格指南中的!-- pyml disable md041 --才不会误报。此外还有一个细节规则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/wikipymarkdownlnt本地可选但 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 内容的编辑环境。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考