企业官网建设流程全解析

如何向 CS自学指南 贡献一门新课程页面并让它进入站点导航？

【免费下载链接】cs-self-learning计算机自学指南项目地址: https://gitcode.com/GitHub_Trending/cs/cs-self-learning

如果你学完了一门 CS 课程，想把它推荐给 CS自学指南（cs-self-learning 仓库，MkDocs Material 主题构建的开源书站点）的读者，需要完成两件事：新增一个课程页面文件，并把这个页面写进 mkdocs.yml 的nav配置，让它出现在站点左侧导航中。本文按仓库 README.md “如何成为贡献者”一节给出的流程，走一遍从建页到上线的完整路径：新建中英两个课程页面、在mkdocs.yml中挂载导航、（可选）在 docs/CS学习规划.md 中补一句导语，最后用与 CI 相同的工具链本地构建验证，再提交 Pull Request。

一门新课程涉及的改动位置：

第一步：按 template.md 创建课程页面

仓库按模块组织课程页面，例如 docs/操作系统/MIT6.S081.md。你的新页面应放进对应的模块目录，文件名自定（与导航中的路径一致即可）。

template.md 的结构如下（代码块为模板骨架，注释内容已省略）：

# 课号：课程名称 ## 课程简介 - 所属大学： - 先修要求： - 编程语言： - 课程难度：🌟🌟🌟 - 预计学时： ## 课程资源 - 课程网站： - 课程视频： - 课程教材： - 课程作业： ## 资源汇总 ## 备注

填写要点（均来自模板原文）：

• 标题格式为课号：课程名称，“课程难度”一栏模板以三星为示例值，按课程实际难度填写。
• 模板在“课程简介”标题后附有一段 HTML 注释，列出简介建议覆盖的内容：课程覆盖的知识点范围、与同类课程相比的优势与特点、学习体验、自学注意点（踩坑、难度预警等）。
• “资源汇总”一节用于列出你学习这门课用到的资源与作业实现所在仓库，模板示例写作@XXX 在学习这门课中用到的所有资源和作业实现都汇总在 user/repo 中——XXX和你的资源仓库地址都是占位符，需替换为你自己的 GitHub ID 和实际仓库；没有对应仓库就不要照抄示例。
• 模板末尾的“备注”一节要求编写文档时遵守 Markdown Rules 与中文简中西文混排要点，可用 VS Code 插件 markdownlint 提示并处理，并且模板明确写着“正文中请删除该节”——交付前把整节删掉。

英文版页面与中文页面同名，扩展名加.en，例如docs/操作系统/MIT6.S081.md对应docs/操作系统/MIT6.S081.en.md。template.en.md 的结构与中文版一一对应：# Course Code: Course Name、## Descriptions（Offered by / Prerequisites / Programming Languages / Difficulty / Class Hour）、## Course Resources（Course Website / Recordings / Textbooks / Assignments）、## Personal Resources。

第二步：在 mkdocs.yml 的 nav 中挂载课程

mkdocs.yml 文件末尾的nav:段定义了站点左侧导航，条目格式为"导航名": "页面路径"，页面路径相对于 docs 目录。以现有的操作系统模块为例：

nav: - 操作系统: - "MIT 6.S081: Operating System Engineering": "操作系统/MIT6.S081.md" - "UCB CS162: Operating Systems and Systems Programming": "操作系统/CS162.md"

把新课程加到所属模块的列表中即可，例如在“操作系统”下追加一行- "你的课程名": "操作系统/你的课程页.md"。如果课程应归入模块下的子分类（如 mkdocs.yml 中“编程入门”下的Python 语言、“深度生成模型”下的大语言模型），则按现有两级嵌套的格式写：

- 编程入门: - Python 语言: - "UCB CS61A: Structure and Interpretation of Computer Programs": "编程入门/Python/CS61A.md"

关于英文名：mkdocs.yml 中的 i18n 插件同时构建 zh（default）和 en 两个站点，并靠nav_translations映射把中文导航名翻译成英文，例如：

plugins: - i18n: nav_translations: 操作系统: Operating Systems

现有模块（操作系统、编译器、机器学习等）都已有映射条目。如果你的新课程挂在已有模块下，通常不需要动nav_translations；只有当你要新增一个此前不在映射表里的一级模块或子分类时，才需要同步补一条中文名: English Name的映射，否则英文站导航将缺少该名称的翻译。

第三步（可选）：在 CS 学习规划中补一句导语

docs/CS学习规划.md 按“模块 → 小节 → 每门课一两句介绍 + 链接”的结构组织，例如其中引用课程页面的写法是[MIT 6.S081](https://link.gitcode.com/i/b3a1c068984b9c7f4011e6e60d6f7cfd)。因为该文档位于 docs 根目录，链接目标写课程页相对 docs 根的路径（./模块/课程.md）即可。这一步 README 表述为“当然你还可以”，属于加分项，不是进入导航的前提。

本地验证：用与 CI 相同的依赖构建站点

仓库 requirements.txt 列出了构建依赖（mkdocs-material==9.5.2、mkdocs-static-i18n==1.2.0、mkdocs-minify-plugin==0.7.1、jinja2==3.1.2等），CI 工作流 .github/workflows/ci.yml 的做法就是安装这份依赖后用 mkdocs 构建部署。提交前在本地按同一工具链验证：

pip3 install -U -r requirements.txt mkdocs build

构建完成后检查三点：

1. 生成的站点输出中出现了你新增的课程页面，且在左侧导航的对应模块下可见；
2. 导航条目文字、页面路径拼写无误——若新课程没进导航，先核对nav里的路径是否以 docs 目录为基准（这是nav配置唯一的隐含基准，也是最容易写错的一处）；
3. 中文、英文两个语言版本都能正常构建（i18n 插件配置了 zh 与 en 两个 locale 且build: true）。

提交 PR 与上线

项目的贡献入口是向仓库提交 Pull Request（见 README.md “如何成为贡献者”），也可以在 issue 或邮件（docs/index.md 中给出的作者邮箱）里先沟通。PR 合并、推送到 master 分支后，CI 会自动执行pip3 install -U -r requirements.txt和mkdocs gh-deploy --force，把站点部署到 mkdocs.yml 中site_url指定的官方地址。届时在站点左侧导航的对应模块下能看到你的课程页、点击进入页面渲染正常，即表示贡献完成。

两点收尾提醒：中英文混排排版上项目会做校对（README 说明了校对依据）；页面中的课程资源链接、视频地址请填真实可访问的地址，课程简介按模板建议把难度预警和踩坑点写清楚——这些是读者自学时最依赖的信息。

【免费下载链接】cs-self-learning计算机自学指南项目地址: https://gitcode.com/GitHub_Trending/cs/cs-self-learning