企业官网建设流程全解析

Tandoor Recipes 文档贡献指南：基于 MkDocs 的文档构建、本地预览与贡献流程

【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes

Tandoor 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 上编辑文档

最轻量的贡献方式完全不需要本地环境：

1. Forkdevelop分支的仓库（文档贡献以develop分支为准，mkdocs.yml中的edit_uri也指向该分支）。
2. 直接在 GitHub 网页端打开docs/下的任意 Markdown 文件进行编辑。
3. 提交改动并创建 Pull Request（PR），等待维护者审阅合并。

这种方式适合小幅修改，例如修正拼写、补充某段配置说明。但网页端无法实时预览 MkDocs 渲染效果，对于涉及大量排版或结构性改动的贡献，更推荐使用方式二。

方式二：使用 IDE 配合 MkDocs 本地预览

如果你习惯使用 VSCode、PyCharm 等 IDE，且希望像写代码一样"改完即预览"，可以采用官方推荐的 IDE 工作流。相比网页端，IDE 的显著优势是可以在提交前完整验证文档渲染结果。

安装 MkDocs 与依赖

首先在项目根目录安装 MkDocs 及其主题、插件依赖，官方给出的命令为：

pip install mkdocs-material mkdocs-include-markdown-plugin

其中：

• mkdocs-material：MkDocs 官方推荐的 Material 主题包，对应 mkdocs.yml 中theme.name: material的配置；
• mkdocs-include-markdown-plugin：对应 mkdocs.yml 中plugins列表里的include-markdown，用于支持文档间的 Markdown 片段复用。

提示：安装依赖前建议先激活项目的 Python 虚拟环境，避免与系统 Python 环境互相污染。

本地启动文档服务

在项目根目录（即包含mkdocs.yml的目录）执行：

mkdocs serve

mkdocs serve会完成以下工作：

1. 读取根目录的 mkdocs.yml，解析主题、扩展、插件与nav导航；
2. 构建 docs 目录下所有 Markdown 文件，在本地启动一个开发服务器；
3. 监听文件变更，当你保存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 Request，PR 合并后你的文档便会随下一次文档站点构建发布。

小结：选择适合你的文档贡献路径

无论选择哪条路径，请始终牢记两点：其一，所有文档均以 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