网站架构

相关源文件

• mkdocs.yml
• requirements.txt

本文档全面概述了支持计算机科学自学指南网站运行的技术架构。它解释了使这个教育资源有效运行的技术、配置和组织结构。有关如何作为学习者使用本指南的信息，请参阅指南入门；有关如何贡献内容的详细信息，请参阅贡献指南。

概述

计算机科学自学指南是使用MkDocs构建的静态网站，MkDocs是一个基于Python的静态网站生成器，专为创建文档网站而设计。该网站利用了多项关键技术和插件，以提供高性能、多语言的教育资源。

来源：mkdocs.yml1-288 requirements.txt1-8

技术栈

该网站架构基于以下关键技术构建：

组件	技术	目的
静态网站生成器	MkDocs	将Markdown内容转换为结构化的HTML
主题	Material for MkDocs	提供视觉设计和用户界面组件
国际化	mkdocs-static-i18n	实现多语言内容（中文和英文）
搜索	MkDocs search plugin	提供全站搜索功能
代码压缩	mkdocs-minify-plugin	优化HTML以提高性能
日期追踪	mkdocs-git-revision-date-plugin	显示内容上次更新时间
链接处理	mkdocs-open-in-new-tab	在新浏览器标签页中打开外部链接

来源：requirements.txt1-8 mkdocs.yml60-125

MkDocs 配置

整个网站配置在mkdocs.yml文件中定义，该文件是网站行为、外观和内容组织的中央控制点。

关键配置要素包括：

1. 网站元数据：基本信息，如网站名称、URL和作者

   site_name: CS自学指南
   site_url: https://csdiy.wiki/
   site_author: PKUFlyingPig
   

2. 主题配置：带有自定义功能的Material主题

   theme:
     name: material
     language: zh
     custom_dir: overrides
   

3. 插件配置：用于网站功能的各种插件

   plugins:
     - i18n
     - search
     - git-revision-date
     - minify
     - open-in-new-tab
   

4. 导航结构：网站层级和页面的定义

   nav:
     - 前言: "index.md"
     - 如何使用这本书: "使用指南.md"
     ...
   

来源：mkdocs.yml1-288

内容组织

网站内容遵循在mkdocs.yml文件的nav部分中定义的层次结构。该结构将教育资源组织成逻辑类别，从基础主题到高级主题逐步深入。

每个内容部分通常包含：

• 顶尖大学的课程信息
• 学习资源（视频、书籍、作业）
• 实施指南/示例
• 先决条件和难度评估

来源：mkdocs.yml135-287

国际化系统

该网站通过mkdocs-static-i18n插件支持中文（默认）和英文两种语言。这允许访问者在不同语言之间切换，同时保持相同的基础内容结构。

mkdocs.yml中的国际化配置定义了：

1. 支持的语言及其区域设置和名称
2. 导航项的翻译映射
3. 特定语言的网站名称和构建设置

例如，英文版本使用nav_translations字典将“前言”翻译为“Foreword”，将“如何使用这本书”翻译为“How To Use The Book”。

nav_translations:
  前言: Foreword
  如何使用这本书: How To Use The Book
  一个仅供参考的CS学习规划: Guideline
  ...

来源：mkdocs.yml60-117

主题和用户界面组件

该网站使用Material for MkDocs主题，并进行了一些自定义，以增强用户体验。主题配置在mkdocs.yml文件的theme部分中定义。

主要主题功能包括：

1. 响应式设计：移动友好，并具有自动导航隐藏功能
2. 亮/暗模式：根据用户偏好自动切换主题
3. 搜索集成：支持高亮显示和建议的全文本搜索
4. 代码格式化：语法高亮和注释支持
5. 自定义覆盖：通过overrides目录进行额外自定义

来源：mkdocs.yml12-53

构建流程

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

构建过程需要requirements.txt中定义的多个Python依赖项：

• mkdocs-material==9.5.2
• mkdocs-minify-plugin==0.7.1
• mkdocs-git-revision-date-plugin
• jinja2==3.1.2
• mkdocs-static-i18n==1.2.0
• mkdocs-open-in-new-tab==1.0.8

来源：requirements.txt1-8

与外部服务集成

该网站架构集成了多个外部服务以增强功能：

1. GitHub仓库：源代码托管和版本控制
2. Google Analytics（谷歌分析）：流量监控和用户行为分析
3. GitHub Pages：托管和提供静态网站服务
4. Giscus：基于GitHub Discussions的评论系统

集成配置在mkdocs.yml文件的repo_name、repo_url和extra部分中定义。

来源：mkdocs.yml7-9 mkdocs.yml127-133

总结

计算机科学自学指南的网站架构结合了MkDocs、Material主题和多个插件，以创建一个功能丰富的教育平台。该架构实现了多语言支持、高效搜索、响应式设计，并能轻松导航庞大的计算机科学学习资源集合。这一基础使得项目能够随内容的增加而扩展，同时保持性能和可用性。