文档系统

相关源文件

• .github/readme-generate.js
• .github/templates/mkdocs_template.yml
• .github/templates/readme_template.md
• .gitignore
• CONTRIBUTING.md
• Dockerfile
• README.md
• requirements.txt
• starsystem/1Star.md
• starsystem/2Star.md
• starsystem/3Star.md
• starsystem/4Star.md
• starsystem/5Star.md

目的与范围

HowToCook 仓库中的文档系统负责生成和维护所有文档构件，包括 README.md 文件、星级评定系统分类以及静态文档网站。该系统确保食谱得到妥善组织、易于发现并以一致的方式呈现给用户。

本文档侧重于文档生成和部署过程的技术架构。有关食谱格式标准的信息，请参阅 食谱格式标准。

系统概览

文档系统包含三个主要组件：

1. README 生成 - 自动创建带有已整理食谱列表的 README.md 文件。
2. 星级系统 - 按难度级别对食谱进行分类并维护索引文件。
3. MkDocs 网站 - 生成具有搜索功能和 PDF 导出功能的静态文档网站。

这些组件协同工作，为用户提供全面的文档体验。

来源： .github/readme-generate.js Dockerfile .github/templates/readme_template.md .github/templates/mkdocs_template.yml

文档生成过程

文档生成过程通过 CI/CD 工作流自动触发。该过程读取所有食谱 Markdown 文件，并根据类别和难度级别进行组织。

来源： .github/readme-generate.js Dockerfile12-17

README 生成

README 生成由 readme-generate.js 脚本处理，该脚本接收食谱 Markdown 文件并将其组织成一个结构化的 README.md 文件。这为用户提供了一种直接从 GitHub 仓库轻松浏览食谱的方式。

关键组件和流程

该脚本执行几项关键操作：

1. 读取仓库中的所有 Markdown 文件
2. 按类别（蔬菜、肉类、水产等）组织食谱
3. 计算每个食谱中的星级评分
4. 在 README 中生成类别部分
5. 创建星级评分索引文件
6. 将内容应用于 README 模板

来源： .github/readme-generate.js65-246 .github/templates/readme_template.md

星级评分系统

星级系统通过难度级别对食谱进行分类，使用户更容易找到符合其技能水平的食谱。该脚本读取每个食谱中的星号符号 (★) 并为每个难度级别创建索引文件。

来源： .github/readme-generate.js65-123 starsystem/1Star.md starsystem/2Star.md starsystem/3Star.md starsystem/4Star.md starsystem/5Star.md

MkDocs 配置和网站生成

MkDocs 的配置由 readme-generate.js 脚本生成，并用于构建静态文档网站。该配置定义了文档网站使用的站点结构、主题和插件。

MkDocs 模板结构

MkDocs 模板配置包括：

• 站点名称和仓库信息
• 主题设置（Material 主题）
• 基于食谱类别的导航结构
• 搜索、PDF 生成等插件

来源： .github/templates/mkdocs_template.yml .github/readme-generate.js164-201

网站生成过程

网站生成过程发生在 Docker 构建过程中。

1. Docker 构建安装 Python 依赖项。
2. MkDocs 处理配置和 Markdown 文件。
3. 生成静态 HTML 网站。
4. 网站通过轻量级静态服务器提供服务。

生成的网站包括：

• 完整的导航结构
• 搜索功能
• 移动端响应式设计
• 暗/亮模式支持
• PDF 导出功能

来源： Dockerfile requirements.txt

文档部署

文档系统提供了多种访问文档的方式：

1. GitHub README - 直接从仓库访问分类食谱列表。
2. 星级评定系统 - GitHub 可浏览的按难度级别分类的食谱索引。
3. Docker 容器 - 本地部署的 Web 文档。
4. PDF 格式 - 可下载的完整文档。

Docker 容器部署提供了一个完整的文档 Web 界面，包括搜索功能和 GitHub 界面中未提供的其他功能。

Docker 部署说明

可以使用以下命令通过 Docker 在本地部署文档：

部署后，文档可通过 http://:5000 访问。PDF 版本可通过 http://:5000/document.pdf 访问。

来源： README.md16-25 Dockerfile

文件结构和代码组织

文档系统依赖于特定的文件组织和代码结构才能正常运行。

关键文件

文件路径	目的
.github/readme-generate.js	用于生成文档的主脚本
.github/templates/readme_template.md	README.md 的模板
.github/templates/mkdocs_template.yml	MkDocs 配置的模板
starsystem/*.md	按难度划分的食谱索引文件
mkdocs.yml	生成的 MkDocs 配置
Dockerfile	用于构建和提供文档的容器定义
requirements.txt	MkDocs 的 Python 依赖项

菜谱组织

食谱按类别组织在 dishes 目录中。

dishes/
├── aquatic/           # Seafood dishes
├── breakfast/         # Breakfast items
├── condiment/         # Sauces and condiments
├── dessert/           # Desserts and sweets
├── drink/             # Beverages
├── meat_dish/         # Meat-based dishes
├── semi-finished/     # Semi-prepared foods
├── soup/              # Soups and porridges
├── staple/            # Main course dishes
├── template/          # Template for new recipes
└── vegetable_dish/    # Vegetable-based dishes

来源： .github/readme-generate.js8-62 README.md59-363

与 CI/CD 流水线的集成

文档系统已集成到项目 CI/CD 管道中，该管道会在仓库发生更改时自动构建和部署文档。

集成确保文档始终与最新的食谱和仓库更改保持同步。

来源： Dockerfile README.md3-8

结论

HowToCook 仓库中的文档系统为管理食谱文档提供了一种全面的方法。通过自动生成 README.md、按难度级别组织食谱以及创建可搜索的文档网站，该系统确保用户能够轻松找到并遵循符合其技能水平和兴趣的食谱。