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

> Learn how to contribute a new course to the cs-self-learning guide. Follow our simple steps to add your course content and resources to the repository.

- Repository: [Yinmin Zhong/cs-self-learning](https://github.com/PKUFlyingPig/cs-self-learning)
- Tags: how-to-guide
- Published: 2026-03-02

---

**To contribute a new course to the CS Self-Learning Guide, copy the [`template.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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:

```bash
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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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:

```yaml
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:

```markdown
| 课程方向 | 课程名称 |
|----------|----------|
| 机器学习 | [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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/template.md):

```markdown

# 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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) like this:

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

```

## Summary

- **Copy the template**: Duplicate [`template.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/template.md), [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.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`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/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.