How to Contribute a New Course to the CS Self-Learning Guide

To contribute a new course to the CS Self-Learning Guide, copy the template.md skeleton into the appropriate docs/ subdirectory, populate the frontmatter with course metadata and resources, and register the file path in the nav section of mkdocs.yml.

The PKUFlyingPig/cs-self-learning repository maintains a comprehensive, community-driven curriculum for computer science self-study. Built as a static documentation site using MkDocs-Material, the guide stores every course as a Markdown file under the docs/ directory. Adding a new course requires no programming—only careful editing of text files to maintain the repository's consistent structure and navigation tree.

Step-by-Step Contribution Workflow

Step 1: Create the Course Markdown File

Start by duplicating the repository-wide template. The template.md file at the repository root provides placeholders for course metadata, including university affiliation, prerequisites, difficulty rating, and estimated study hours.

Copy the template to the appropriate subject folder:

cp template.md docs/<category>/<CourseID>.md

For example, a machine learning course might be saved as docs/机器学习/ML202.md.

Fill in the frontmatter following the established Chinese-English mixed typography guidelines. Include a brief introduction, official resource links, and any community-contributed code repositories in the 资源汇总 section.

Step 2: Register the Course in mkdocs.yml Navigation

Open mkdocs.yml and locate the nav: block. This YAML file defines the left-hand navigation tree for the MkDocs site. Insert a new entry under the correct top-level section using the format:

nav:
  - 前言: "index.md"
  - 机器学习:
      - "Stanford CS229": "机器学习/CS229.md"
      - "Your New Course": "机器学习/ML202.md"  # ← new entry

The value must use the relative path from the docs/ directory (e.g., "机器学习/ML202.md"). The key (course name) appears as the display text in the navigation menu.

Step 3: Update the Learning Roadmap (Optional)

If your course belongs to a structured learning path documented in docs/CS学习规划.md, append a row to the Markdown table linking to your new file:

| 课程方向 | 课程名称 |
|----------|----------|
| 机器学习 | [ML202: Advanced Topics](机器学习/ML202.md) |

This ensures the central roadmap in docs/CS学习规划.md remains coherent with the expanded curriculum.

Code Examples and Templates

Course File Structure (from template.md)

Save your content following this structure derived from template.md:

# CS101: Introduction to Algorithms

## 课程简介

- 所属大学：MIT
- 先修要求：基本的编程经验（Python/C++）
- 编程语言：Python
- 课程难度：🌟🌟🌟🌟
- 预计学时：40 小时

本课程系统讲解排序、搜索、图论以及动态规划等核心算法。相较于同类课程，它提供了大量可直接运行的 Jupyter Notebook 示例。

## 课程资源

- 课程网站： https://ocw.mit.edu/courses/6-006-introduction-to-algorithms-fall-2020/
- 课程视频： https://youtube.com/playlist?list=PLXXXX
- 课程教材： 《Introduction to Algorithms》 (Cormen et.)
- 课程作业： 练习题位于 `assets/CS101/assignments/`

## 资源汇总

@XYZ 在学习这门课中实现的所有代码和作业均汇总在 https://github.com/XYZ/CS101-resources

## 备注

请遵循 Markdown Rules 与中文-英文混排要点，确保文档在 MkDocs 中渲染良好。

Navigation Configuration Example

Add your course to the tree in mkdocs.yml like this:

nav:
  - 前言: "index.md"
  - 计算机系统基础:
      - "CMU 15-213: CSAPP": "计算机系统基础/CSAPP.md"
      - "CS101: Introduction to Algorithms": "算法/CS101.md"   # ← new line

Summary

• Copy the template: Duplicate template.md from the repository root into the appropriate docs/<category>/ directory with a descriptive filename.
• Populate metadata: Fill in university, prerequisites, difficulty stars, and resource links following the established schema.
• Register navigation: Add the course to the nav block in mkdocs.yml using the relative path from the docs/ folder.
• Update roadmap (optional): Link the course in docs/CS学习规划.md if it fits a defined learning path.
• Submit via PR: Fork the repository, commit your changes, and open a Pull Request; the CI pipeline in .github/workflows/ci.yml automatically validates Markdown linting and site build integrity.

Frequently Asked Questions

Do I need programming skills to contribute a course?

No. The CS Self-Learning Guide accepts contributions as plain Markdown text. You only need to edit text files (template.md, mkdocs.yml) and follow the repository's formatting conventions for mixed Chinese-English content. No code execution or software compilation is required to add a course entry.

Where should I place the new course file?

Save the Markdown file under the appropriate subject folder within docs/, such as docs/机器学习/ for machine learning or docs/系统安全/ for security courses. The file path must match the relative path you specify in mkdocs.yml. Refer to existing entries like docs/机器学习/ML202.md for directory naming conventions.

How does the repository validate my contribution?

The repository uses GitHub Actions defined in .github/workflows/ci.yml to automatically build the MkDocs site and check for Markdown linting errors when you submit a Pull Request. This ensures your new course renders correctly and does not break the site's navigation structure before merging.

Can I contribute courses that are not taught in Chinese?

Yes. The guide welcomes high-quality courses from any university worldwide. When contributing, provide the course metadata in Chinese as per the template.md structure, but link to original English (or other language) resources. The documentation standard follows Chinese-English mixed typography guidelines to maintain readability for the primary audience.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}