Super Productivity Wiki 文档架构解析Diátaxis 框架在开源项目中的落地实践【免费下载链接】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-productivitySuper Productivity 是一个集任务管理、时间盒Timeboxing与时间追踪于一体的效率应用其配套的开源 Wiki 采用 DiátaxisDiátaxis Framework文档分类框架来组织全部文档。本文以仓库中的元文档 0.-Meta-Diataxis.md 为核心结合 Wiki 的实际目录、索引页、风格规范与 CI 校验脚本完整讲解四种文档模式如何映射到 Wiki 的分区、编号与写作规范。读完本文你将理解这套可复用的文档治理方案并能按仓库约定正确判断一篇文档该放入哪个分区、如何命名、如何通过链接与静态检查。一、Diátaxis四种文档模式的分类框架Diátaxis 是一套面向技术文档质量与系统性组织的框架核心思想是把文档按用户需求分为四种互补的模式mode每一种模式回答一类特定问题模式回答的问题典型形态Quickstart快速上手教你如何做一件事线性引导的学习路径帮用户完成第一个成功的工作流How-To Guide操作指南为解决问题或完成任务应该做什么聚焦单一任务的分步操作说明Reference参考资料某个对象的事实与静态信息配置项、API、快捷键、平台差异等客观描述Concepts概念某个东西背后的理论、上下文、目的与用途背景知识与心智模型这四种模式不是简单的目录分类而是围绕读者意图的系统化组织方式——用户在检索文档时通常带着我现在想做什么的明确意图框架让文档与意图精确对齐。引述自仓库元文档0.-Meta-Diataxis.md该文档同时引用了 diataxis.fr 对四模式的完整定义。二、框架的落地Wiki 的四个编号分区Diátaxis 只是理论框架真正决定 Wiki 可维护性的是其实现——即 0.00-Wiki-Structure-and-Organization.md 中定义的编号分区结构。仓库将 Wiki 页面按用途划分为 04 五个分区0 — Meta贡献规范、结构、风格与维护指引即本文所依据的元文档所在分区1 — Quickstarts引导式学习路径面向第一个成功工作流2 — How-to guides聚焦完成某个具体任务的分步指南3 — Reference对设置、API、快捷键、平台差异与受支持集成的客观事实描述4 — Concepts用于理解产品行为背景与心智模型的知识。每个分区都有一个编号为X.00的索引页作为入口1.00-Quickstarts.md — 快速上手索引2.00-How_To.md — 操作指南索引21 篇 How-To 全量清单3.00-Reference.md — 参考资料索引API、设置、快捷键、短语法、主题等 9 篇4.00-Concepts.md — 概念索引视图、任务属性、时间记录、数据管理等 22 篇。导航入口是Home与_Sidebar二者与各分区索引页共同构成 Wiki 的信息骨架。这种四类模式 编号分区的映射正是 Diátaxis 从理论走向可维护仓库的关键一步。三、四种模式在仓库中的真实样例仅看定义还不够仓库中的真实页面展示了每种模式的写作形态差异Quickstart线性引导一次跑通1.01-First-Steps.md 是典型的快速上手从打开 Web 应用 → 添加任务 → 时间追踪 → 任务详情 → 删除任务 → 完成一天线性推进并明确告诉读者可以先跳过同步之后再看 1.02-Configure-Data-Synchronization。它不追求穷尽功能而是让用户在最短路径上获得第一个成功体验并在结尾给出Where to Go next延伸入口。How-To单任务、可操作、可验证2.09-Configure-Sync-Backend.md 是 How-To 的范本围绕配置同步后端这一个任务逐 providerSuperSync、Dropbox、OneDrive、Nextcloud、WebDAV、Local File给出必填字段、取值示例如 Nextcloud 的Server URL示例https://cloud.example.com、易错点Nextcloud 用户名必须是 WebDAV 用户 ID 而非邮箱、以及故障排错OneDriveHTTP 400与AADSTS9002327的成因。整个 2.00-How_To.md 索引中的 21 个页面均遵循明确任务 → 分步操作 → 参数说明的同一范式。Reference事实静态、不夹带过程3.00-Reference.md 索引下的页面如 3.03-Keyboard-Shortcuts.md、3.02-Settings-and-Preferences.md以对象—属性—值的客观结构呈现信息刻意不做引导性叙述与 Quickstart/How-To 形成互补。Concepts解释为什么4.00-Concepts.md 索引下如 4.14-How-Time-Is-Logged.md、4.19-Metrics.md 等页面讲解的是时间如何被记录、指标如何计算这类背景知识帮助用户在理解产品心智模型后再去操作。四类页面各司其职、互相链接如 Quickstart 链接到 How-To 与 Reference这正是 Diátaxis四模式协同在真实项目中的体现。四、编号命名可维护性的第一道防线0.00-Wiki-Structure-and-Organization.md 明确要求数字前缀让页面在 GitHub Wiki 中保持分组不应随意重命名因为既有链接与书签依赖这些名称。同时 0.01-Style-Guide.md 补充了命名细则扁平结构除assets/图片目录外所有笔记平铺在docs/wiki下避免子目录导致重名冲突GitHub 会把Dir1/note.md与Dir2/note.md折叠成同一页面空格全部替换为连字符如API Reference.md与API-Reference.md会被 GitHub 静默去重必须主动用-避免冲突使用 Wiki 风格链接[[page-name]]比 Markdown 链接更易手写GitHub 与 Obsidian 兼容唯一差异是 GitHub 渲染图片不需要!禁用别名语法[[9.Test-Note|Test Note]]会渲染为无法解析的../wiki/Test-Note仓库明确规定不使用该语法。这些约定直接服务于文档可以低成本迁移到其他 Wiki 程序或静态站点生成器SSG的目标。五、写作流程从选题到提交的五步规范0.00-Wiki-Structure-and-Organization.md 给出了新增或更新页面的标准流程依据页面用途选择匹配的分区Quickstart / How-To / Reference / Concepts / Meta使用一个清晰的 H1并遵循 0.01-Style-Guide.md 的风格规范将页面链接到所在分区的索引页若是主用户旅程的一部分还需加入_Sidebar对照当前仓库核验命令、路径、设置与行为描述是否准确在提交前按 0.02-Wiki-QA-and-Maintenance.md 执行质量检查。该流程同时强调一条重要原则避免占位页与整段复制的配置堆砌。一份简短但保持更新、并链接到权威代码或指南的页面优于一份详细却会随时间漂移drift的长文——这是对抗文档腐化的核心策略。六、质量保障本地校验与 CI 双保险Wiki 的 PR 在 CI 中会自动运行 Markdown 静态检查与本地链接校验详见 0.02-Wiki-QA-and-Maintenance.md。提交前建议在本地执行npm run docs:check-links pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wikidocs:check-links是仓库自带的链接检查器无第三方依赖会校验 Markdown 链接、HTMLhref/src属性、图片与 Wiki 链接并拒绝别名语法pymarkdownlnt是 CI 必需的 Markdown lint 工具本地可选安装Arch 下pipx install pymarkdownlnt外部 URL 不会被自动爬取避免临时网络故障阻塞 PR需要贡献者手动打开并替换失效链接且优先使用稳定的主要来源。风格规范还提供了针对 lint 规则的细粒度控制单篇笔记可通过首行 HTML 注释!-- pyml disable md041 --豁免 MD041首行 H1规则若需全库豁免可在.github/workflows/wiki-sync.yml的--disable-rules中追加md041。推荐将 lint 配置为 Git pre-commit 钩子确保每次提交都通过 CIcat .git/hooks/pre-commit EOF #!/bin/sh set -eu pymarkdownlnt --disable-rules line-length scan docs/wiki EOF chmod x .git/hooks/pre-commit七、风格细则缩进、锚点与可移植性0.01-Style-Guide.md 中还有若干容易忽略的硬性约定缩进禁用 Tab只使用两个空格锚点链接在同一笔记内锚点同样是扁平的空格转为连字符、大写转为小写优先保持笔记简短以从根本上避免深层锚点引用可移植性所有格式选择CommonMark、GitHub Flavored Markdown、GitHub Wiki 限制、Obsidian Flavored Markdown 的兼容都服务于能相对轻松地迁移到另一个服务这一目标。这些细节共同保证了 Wiki 在 GitHub、Obsidian 与未来可能的 SSG 之间自由迁移而不损坏。结语一套可复制的文档治理模板Super Productivity 的 Wiki 证明了 Diátaxis 的价值不在于理论本身而在于它被翻译成编号分区、命名规则、写作流程与 CI 检查这套可执行约束。对任何希望整理自身文档的开源项目这套方案都可直接借鉴先用 Diátaxis 划分四类文档意图再用编号与扁平结构保证链接稳定最后用 lint 链接校验守住质量底线。深入理解本仓库可从 0.-Meta-Diataxis.md 出发依次阅读 0.00-Wiki-Structure-and-Organization.md、0.01-Style-Guide.md 与 0.02-Wiki-QA-and-Maintenance.md再对照各分区索引页观察四类模式的实际写作差异。【免费下载链接】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），仅供参考 Super Productivity Wiki 文档架构解析：Diátaxis 框架在开源项目中的落地实践
Super Productivity Wiki 文档架构解析Diátaxis 框架在开源项目中的落地实践【免费下载链接】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-productivitySuper Productivity 是一个集任务管理、时间盒Timeboxing与时间追踪于一体的效率应用其配套的开源 Wiki 采用 DiátaxisDiátaxis Framework文档分类框架来组织全部文档。本文以仓库中的元文档 0.-Meta-Diataxis.md 为核心结合 Wiki 的实际目录、索引页、风格规范与 CI 校验脚本完整讲解四种文档模式如何映射到 Wiki 的分区、编号与写作规范。读完本文你将理解这套可复用的文档治理方案并能按仓库约定正确判断一篇文档该放入哪个分区、如何命名、如何通过链接与静态检查。一、Diátaxis四种文档模式的分类框架Diátaxis 是一套面向技术文档质量与系统性组织的框架核心思想是把文档按用户需求分为四种互补的模式mode每一种模式回答一类特定问题模式回答的问题典型形态Quickstart快速上手教你如何做一件事线性引导的学习路径帮用户完成第一个成功的工作流How-To Guide操作指南为解决问题或完成任务应该做什么聚焦单一任务的分步操作说明Reference参考资料某个对象的事实与静态信息配置项、API、快捷键、平台差异等客观描述Concepts概念某个东西背后的理论、上下文、目的与用途背景知识与心智模型这四种模式不是简单的目录分类而是围绕读者意图的系统化组织方式——用户在检索文档时通常带着我现在想做什么的明确意图框架让文档与意图精确对齐。引述自仓库元文档0.-Meta-Diataxis.md该文档同时引用了 diataxis.fr 对四模式的完整定义。二、框架的落地Wiki 的四个编号分区Diátaxis 只是理论框架真正决定 Wiki 可维护性的是其实现——即 0.00-Wiki-Structure-and-Organization.md 中定义的编号分区结构。仓库将 Wiki 页面按用途划分为 04 五个分区0 — Meta贡献规范、结构、风格与维护指引即本文所依据的元文档所在分区1 — Quickstarts引导式学习路径面向第一个成功工作流2 — How-to guides聚焦完成某个具体任务的分步指南3 — Reference对设置、API、快捷键、平台差异与受支持集成的客观事实描述4 — Concepts用于理解产品行为背景与心智模型的知识。每个分区都有一个编号为X.00的索引页作为入口1.00-Quickstarts.md — 快速上手索引2.00-How_To.md — 操作指南索引21 篇 How-To 全量清单3.00-Reference.md — 参考资料索引API、设置、快捷键、短语法、主题等 9 篇4.00-Concepts.md — 概念索引视图、任务属性、时间记录、数据管理等 22 篇。导航入口是Home与_Sidebar二者与各分区索引页共同构成 Wiki 的信息骨架。这种四类模式 编号分区的映射正是 Diátaxis 从理论走向可维护仓库的关键一步。三、四种模式在仓库中的真实样例仅看定义还不够仓库中的真实页面展示了每种模式的写作形态差异Quickstart线性引导一次跑通1.01-First-Steps.md 是典型的快速上手从打开 Web 应用 → 添加任务 → 时间追踪 → 任务详情 → 删除任务 → 完成一天线性推进并明确告诉读者可以先跳过同步之后再看 1.02-Configure-Data-Synchronization。它不追求穷尽功能而是让用户在最短路径上获得第一个成功体验并在结尾给出Where to Go next延伸入口。How-To单任务、可操作、可验证2.09-Configure-Sync-Backend.md 是 How-To 的范本围绕配置同步后端这一个任务逐 providerSuperSync、Dropbox、OneDrive、Nextcloud、WebDAV、Local File给出必填字段、取值示例如 Nextcloud 的Server URL示例https://cloud.example.com、易错点Nextcloud 用户名必须是 WebDAV 用户 ID 而非邮箱、以及故障排错OneDriveHTTP 400与AADSTS9002327的成因。整个 2.00-How_To.md 索引中的 21 个页面均遵循明确任务 → 分步操作 → 参数说明的同一范式。Reference事实静态、不夹带过程3.00-Reference.md 索引下的页面如 3.03-Keyboard-Shortcuts.md、3.02-Settings-and-Preferences.md以对象—属性—值的客观结构呈现信息刻意不做引导性叙述与 Quickstart/How-To 形成互补。Concepts解释为什么4.00-Concepts.md 索引下如 4.14-How-Time-Is-Logged.md、4.19-Metrics.md 等页面讲解的是时间如何被记录、指标如何计算这类背景知识帮助用户在理解产品心智模型后再去操作。四类页面各司其职、互相链接如 Quickstart 链接到 How-To 与 Reference这正是 Diátaxis四模式协同在真实项目中的体现。四、编号命名可维护性的第一道防线0.00-Wiki-Structure-and-Organization.md 明确要求数字前缀让页面在 GitHub Wiki 中保持分组不应随意重命名因为既有链接与书签依赖这些名称。同时 0.01-Style-Guide.md 补充了命名细则扁平结构除assets/图片目录外所有笔记平铺在docs/wiki下避免子目录导致重名冲突GitHub 会把Dir1/note.md与Dir2/note.md折叠成同一页面空格全部替换为连字符如API Reference.md与API-Reference.md会被 GitHub 静默去重必须主动用-避免冲突使用 Wiki 风格链接[[page-name]]比 Markdown 链接更易手写GitHub 与 Obsidian 兼容唯一差异是 GitHub 渲染图片不需要!禁用别名语法[[9.Test-Note|Test Note]]会渲染为无法解析的../wiki/Test-Note仓库明确规定不使用该语法。这些约定直接服务于文档可以低成本迁移到其他 Wiki 程序或静态站点生成器SSG的目标。五、写作流程从选题到提交的五步规范0.00-Wiki-Structure-and-Organization.md 给出了新增或更新页面的标准流程依据页面用途选择匹配的分区Quickstart / How-To / Reference / Concepts / Meta使用一个清晰的 H1并遵循 0.01-Style-Guide.md 的风格规范将页面链接到所在分区的索引页若是主用户旅程的一部分还需加入_Sidebar对照当前仓库核验命令、路径、设置与行为描述是否准确在提交前按 0.02-Wiki-QA-and-Maintenance.md 执行质量检查。该流程同时强调一条重要原则避免占位页与整段复制的配置堆砌。一份简短但保持更新、并链接到权威代码或指南的页面优于一份详细却会随时间漂移drift的长文——这是对抗文档腐化的核心策略。六、质量保障本地校验与 CI 双保险Wiki 的 PR 在 CI 中会自动运行 Markdown 静态检查与本地链接校验详见 0.02-Wiki-QA-and-Maintenance.md。提交前建议在本地执行npm run docs:check-links pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wikidocs:check-links是仓库自带的链接检查器无第三方依赖会校验 Markdown 链接、HTMLhref/src属性、图片与 Wiki 链接并拒绝别名语法pymarkdownlnt是 CI 必需的 Markdown lint 工具本地可选安装Arch 下pipx install pymarkdownlnt外部 URL 不会被自动爬取避免临时网络故障阻塞 PR需要贡献者手动打开并替换失效链接且优先使用稳定的主要来源。风格规范还提供了针对 lint 规则的细粒度控制单篇笔记可通过首行 HTML 注释!-- pyml disable md041 --豁免 MD041首行 H1规则若需全库豁免可在.github/workflows/wiki-sync.yml的--disable-rules中追加md041。推荐将 lint 配置为 Git pre-commit 钩子确保每次提交都通过 CIcat .git/hooks/pre-commit EOF #!/bin/sh set -eu pymarkdownlnt --disable-rules line-length scan docs/wiki EOF chmod x .git/hooks/pre-commit七、风格细则缩进、锚点与可移植性0.01-Style-Guide.md 中还有若干容易忽略的硬性约定缩进禁用 Tab只使用两个空格锚点链接在同一笔记内锚点同样是扁平的空格转为连字符、大写转为小写优先保持笔记简短以从根本上避免深层锚点引用可移植性所有格式选择CommonMark、GitHub Flavored Markdown、GitHub Wiki 限制、Obsidian Flavored Markdown 的兼容都服务于能相对轻松地迁移到另一个服务这一目标。这些细节共同保证了 Wiki 在 GitHub、Obsidian 与未来可能的 SSG 之间自由迁移而不损坏。结语一套可复制的文档治理模板Super Productivity 的 Wiki 证明了 Diátaxis 的价值不在于理论本身而在于它被翻译成编号分区、命名规则、写作流程与 CI 检查这套可执行约束。对任何希望整理自身文档的开源项目这套方案都可直接借鉴先用 Diátaxis 划分四类文档意图再用编号与扁平结构保证链接稳定最后用 lint 链接校验守住质量底线。深入理解本仓库可从 0.-Meta-Diataxis.md 出发依次阅读 0.00-Wiki-Structure-and-Organization.md、0.01-Style-Guide.md 与 0.02-Wiki-QA-and-Maintenance.md再对照各分区索引页观察四类模式的实际写作差异。【免费下载链接】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），仅供参考