Tandoor Recipes 文档贡献指南基于 MkDocs 的文档构建、本地预览与贡献流程【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipesTandoor Recipes食谱管理应用的全部用户文档由仓库根目录 docs 下的 Markdown 文件经 MkDocs 构建生成。本文面向希望参与文档维护的贡献者系统讲解文档的构建机制mkdocs.yml 配置、目录结构与插件体系并逐一介绍三种官方认可的贡献方式直接在 GitHub 上编辑、使用 IDE 配合mkdocs serve本地预览、以及低技术门槛的素材提交方式。阅读本文后你将能独立搭建文档本地开发环境、验证文档渲染效果并正确提交文档贡献。文档从何而来docs 目录与 MkDocs 构建体系Tandoor 的文档并非独立站点源码而是由位于 docs 目录下的 Markdown 文件构建而成。整个构建链路以仓库根目录的 mkdocs.yml 为配置入口该文件定义了站点名称、主题、扩展与导航结构。目录结构一览docs 目录按主题划分与 mkdocs.yml 中的nav导航一一对应docs/index.md文档首页包含项目简介与核心特性概览docs/install/安装指南覆盖 Docker、Kubernetes、Unraid、Synology、ArchLinux、HomeAssistant、手动安装等场景docs/features/功能文档如 templating模板、shopping购物清单、authentication认证、automation自动化、connectors连接器、import_export导入导出、telegram_bot、ai 等docs/system/系统运维主题包括配置、升级、SQLite 迁移到 PostgreSQL、权限系统、备份docs/contribute/贡献指南包含总览、翻译、文档即本篇、代码规范、IDE 配置与相关项目docs/stylesheets/extra.css站点自定义样式用于定制 MkDocs Material 主题的主色与强调色mkdocs.yml 核心配置解读仓库根目录的 mkdocs.yml 是文档构建的大脑关键配置项如下site_name: Tandoor Recipes站点标题会显示在浏览器标签与页面头部。theme: name: material使用 MkDocs 的 Material 主题并配置了logo、favicon均指向logo_color.svg以及深色palette方案scheme: slate。markdown_extensions启用了三个 Markdown 扩展直接影响文档可使用的语法能力admonition支持!!! note、!!! tip、!!! danger、!!! success等提示框语法你在本文及 contribute.md、guidelines.md 中看到的彩色提示框即由此渲染pymdownx.highlight与pymdownx.superfences提供带语法高亮的代码块以及嵌套块级元素支持。plugins启用两个插件include-markdown即 documentation.md 中安装命令所对应的mkdocs-include-markdown-plugin用于在文档中按引用方式复用其他 Markdown 片段search为站点提供全文检索能力。extra_css引入stylesheets/extra.css其内部通过 CSS 变量将 Material 主题的主色调调整为 Tandoor 的暖色系如--md-primary-fg-color: #ddbf86实现品牌化定制。nav以嵌套列表声明全站导航层级新增文档后需要在此处注册才能在站点侧边栏中出现。方式一直接在 GitHub 上编辑文档最轻量的贡献方式完全不需要本地环境Forkdevelop分支的仓库文档贡献以develop分支为准mkdocs.yml中的edit_uri也指向该分支。直接在 GitHub 网页端打开docs/下的任意 Markdown 文件进行编辑。提交改动并创建 Pull RequestPR等待维护者审阅合并。这种方式适合小幅修改例如修正拼写、补充某段配置说明。但网页端无法实时预览 MkDocs 渲染效果对于涉及大量排版或结构性改动的贡献更推荐使用方式二。方式二使用 IDE 配合 MkDocs 本地预览如果你习惯使用 VSCode、PyCharm 等 IDE且希望像写代码一样改完即预览可以采用官方推荐的 IDE 工作流。相比网页端IDE 的显著优势是可以在提交前完整验证文档渲染结果。安装 MkDocs 与依赖首先在项目根目录安装 MkDocs 及其主题、插件依赖官方给出的命令为pip install mkdocs-material mkdocs-include-markdown-plugin其中mkdocs-materialMkDocs 官方推荐的 Material 主题包对应 mkdocs.yml 中theme.name: material的配置mkdocs-include-markdown-plugin对应 mkdocs.yml 中plugins列表里的include-markdown用于支持文档间的 Markdown 片段复用。提示安装依赖前建议先激活项目的 Python 虚拟环境避免与系统 Python 环境互相污染。本地启动文档服务在项目根目录即包含mkdocs.yml的目录执行mkdocs servemkdocs serve会完成以下工作读取根目录的 mkdocs.yml解析主题、扩展、插件与nav导航构建 docs 目录下所有 Markdown 文件在本地启动一个开发服务器监听文件变更当你保存docs/下的任意.md文件时自动重新构建并热更新页面。随后在浏览器中打开http://127.0.0.1:8000即可实时查看文档渲染效果包括导航结构、admonition 提示框、代码高亮与检索功能是否正常。这条命令是文档贡献流程中最核心的验证手段在提交 PR 之前务必用它对所有改动过的页面做一次渲染检查防止 Markdown 语法错误或内部链接失效进入主线。文档写作与检查要点结合 mkdocs.yml 中启用的扩展写作文档时可以放心使用以下语法!!! tip/!!! danger/!!! success/!!! info等 admonition 提示框带围栏fenced code block且支持语法高亮的代码块--8--或插件语法进行跨文件片段复用。同时注意mkdocs.yml的nav已声明了站点导航层级若新增文档文件需要在对应位置补充 nav 条目否则页面不会出现在侧边栏中。方式三低技术门槛的素材提交如果不想接触 Git 或 Markdown官方还提供了第三种完全无门槛的贡献途径用任何文字处理器撰写文档甚至可以录制一段视频然后提交一个 Feature Request在请求中附上你的文档素材并说明希望有人将内容补充到 Tandoor 文档中。这种方式适合不具备技术背景但熟悉特定场景的用户——例如你深入使用过某个非标准部署方式或冷门功能可以先用 Word、纯文本甚至视频把经验沉淀下来再由社区成员整理成正式文档。它绕过了 Git 工作流但同样能为文档库提供宝贵的一手素材。文档贡献的整体规范与协作细节docs/contribute/documentation.md是文档贡献的入口说明与之配套的还有一整套贡献协作规范建议在动手前通读贡献总览说明翻译、Issue/Feature Request、文档、代码四类贡献的整体框架文档贡献被定位为最轻松的回报方式不需要深入的技术知识既可以撰写非标准安装/配置指南也可以围绕 authentication、automation 等高级功能撰写使用教程。代码贡献指南涉及代码提交时需遵守的 flake8 / yapf / isort / prettier 规范、pytest-django 测试要求以及对大型功能先提交技术描述再动手的约定。翻译贡献指南文档之外的界面翻译工作流基于 Weblate或manage.py makemessages -l 语言代码 -i venv。功能贡献指南 与 集成功能指南针对特定类型功能如导入/导出集成的专项贡献文档。贡献署名与 PR 流程项目维护者鼓励贡献者在 CONTRIBUTERS.md 中自行添加署名以记录对项目代码/特性、翻译等的贡献。文档贡献的最终落地路径同样是 Fork → 修改 → Pull RequestPR 合并后你的文档便会随下一次文档站点构建发布。小结选择适合你的文档贡献路径贡献方式适用场景核心动作直接在 GitHub 编辑小修小补错别字、补充段落Forkdevelop→ 网页编辑 → PRIDE mkdocs serve结构性改动、排版复杂、需本地验证pip install mkdocs-material mkdocs-include-markdown-plugin→mkdocs serve→ 浏览器预览低技术素材提交无 Git 经验但有一手经验用文档/视频整理素材 → 提交 Feature Request无论选择哪条路径请始终牢记两点其一所有文档均以 docs 目录下的 Markdown 为唯一事实来源构建行为由根目录 mkdocs.yml 驱动其二提交前务必确认新增页面已正确注册到nav、内部相对链接可正常解析、admonition 与代码块等扩展语法渲染无误。遵循以上流程你就能为 Tandoor Recipes 的文档库持续贡献高质量内容。【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考