构建过程与依赖

相关源文件

• mkdocs.yml
• requirements.txt

本文档解释了《计算机科学自学指南》静态网站的生成方式，包括构建工作流程、所需的 Python 包及其用途。有关 MkDocs 配置结构的信息，请参见MkDocs 配置。有关国际化系统的详细信息，请参见国际化系统。

概述

《计算机科学自学指南》网站是一个使用 MkDocs 构建的静态网站，MkDocs 是一个基于 Python 的文档生成器，能将 Markdown 文件转换为功能齐全的 HTML 网站。构建过程会获取 Markdown 内容，应用 Material 主题，通过各种插件进行处理，并输出一个可部署的网站。

来源：mkdocs.yml requirements.txt

必需的依赖项

《计算机科学自学指南》依赖多个 Python 包才能正常运行。这些依赖项在requirements.txt文件中指定。

包	版本	目的
mkdocs-material	9.5.2	MkDocs 的 Material 主题，提供现代化的 UI 组件
mkdocs-minify-plugin	0.7.1	优化输出的 HTML、CSS 和 JavaScript 文件以提升性能
mkdocs-git-revision-date-plugin	最新版	将 Git 中的最后修订日期添加到每个页面
jinja2	3.1.2	MkDocs 用于渲染的模板引擎
mkdocs-static-i18n	1.2.0	启用多语言国际化支持
mkdocs-open-in-new-tab	1.0.8	使外部链接在新浏览器标签页中打开

来源：requirements.txt1-6

构建过程工作流

构建过程通过多个阶段将 Markdown 内容转换为静态 HTML 网站

来源：mkdocs.yml60-125

MkDocs 配置与插件链

mkdocs.yml文件定义了整个构建配置，包括处理内容的插件链。每个插件在构建管道中执行特定功能。

来源：mkdocs.yml1-10 mkdocs.yml60-125

插件功能详情

i18n (国际化) 插件

i18n插件对于提供多语言支持至关重要。它会处理中文（默认）和英文内容。

来源：mkdocs.yml61-117

搜索插件

搜索插件支持中文和英文，提供网站搜索功能。

来源：mkdocs.yml118-121 mkdocs.yml22-28

构建与部署过程

完整的构建和部署过程涉及多个步骤

1. 设置环境：安装 Python 和requirements.txt中所需的依赖项
2. 内容创建：在仓库中编写或更新 Markdown 文件
3. 构建配置：在mkdocs.yml中定义站点结构和设置
4. 本地测试：运行mkdocs serve在本地预览网站
5. 构建网站：执行mkdocs build生成静态网站
6. 部署：将更改推送到 GitHub，这将触发自动部署到 csdiy.wiki

来源：mkdocs.yml requirements.txt

主题配置

Material 主题为网站提供了视觉基础。它配置了特定的功能和自定义项

来源：mkdocs.yml12-53

依赖管理

管理依赖项对于构建过程的正常运行至关重要。以下是设置环境的方法

1. 创建 Python 虚拟环境

2. 安装所有必需的依赖项

3. 验证安装

该项目为某些包使用了特定版本，以确保兼容性

• mkdocs-material: 9.5.2
• mkdocs-minify-plugin: 0.7.1
• jinja2: 3.1.2

对于其他包，则使用最新版本。

来源：requirements.txt1-6

常见构建问题和故障排除

构建网站时，可能会遇到以下常见问题

1. 依赖冲突：确保您使用的是requirements.txt中指定的精确版本
2. 插件错误：检查所有插件是否正确安装和配置
3. Markdown 语法问题：验证所有 Markdown 文件是否使用正确的语法
4. 主题自定义问题：验证主题覆盖是否正确实现

如果遇到 i18n 插件或多语言内容的问题，请参见国际化系统了解更多详情。

来源：mkdocs.yml60-125 requirements.txt