# How the CS Self-Learning Guide Is Organized by Topic

> Learn how the CS self-learning guide organizes its content by topic. Discover its structure defined in mkdocs.yml, supporting bilingual Markdown files.

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

---

**The CS Self-Learning Guide organizes content into topic-specific clusters defined in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml), mapping navigation entries to Markdown files under the `docs/` directory with bilingual support.**

The PKUFlyingPig/cs-self-learning repository is a Markdown-driven knowledge base built with MkDocs-Material. Its entire structure is data-driven through the [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) configuration file, which creates a logical hierarchy of computer science topics ranging from fundamental mathematics to advanced systems.

## Topic Hierarchy in mkdocs.yml

The navigation tree is declared under the `nav:` key in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml), grouping content into logical **topic clusters**. Each cluster corresponds to a subdirectory under `docs/` and contains individual course pages as Markdown files.

The repository includes clusters such as:

- **数学基础** (Fundamental Mathematics) → `docs/数学基础/` (e.g., [`MITmaths.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/MITmaths.md) for MIT 18.01/18.02 Calculus)
- **数学进阶** (Advanced Mathematics) → `docs/数学进阶/` (e.g., [`CS70.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS70.md) for UCB CS70 Discrete Math)
- **编程入门** (Fundamental Programming) → `docs/编程入门/` (e.g., [`MIT-Missing-Semester.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/MIT-Missing-Semester.md))
- **电子基础** (Fundamental Electronics) → `docs/电子基础/` (e.g., [`EE16.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/EE16.md) for EE16A&B)
- **数据结构与算法** (Data Structures and Algorithms) → `docs/数据结构与算法/` (e.g., [`CS61B.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS61B.md))
- **软件工程** (Software Engineering) → `docs/软件工程/` (e.g., [`CS169.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS169.md) for UCB CS169)
- **计算机系统基础** (Computer Systems Principles) → `docs/计算机系统基础/` (e.g., [`CSAPP.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CSAPP.md) for CMU CSAPP)
- **体系结构** (Computer Architecture) → `docs/体系结构/` (e.g., [`CS61C.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS61C.md) for UCB CS61C)
- **操作系统** (Operating Systems) → `docs/操作系统/` (e.g., [`MIT6.S081.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/MIT6.S081.md))
- **计算机网络** (Computer Networking) → `docs/计算机网络/` (e.g., [`topdown_ustc.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/topdown_ustc.md) for the Top-Down Approach)
- **数据库系统** (Database Systems) → `docs/数据库系统/` (e.g., [`15445.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/15445.md) for CMU 15-445)
- **编译原理** (Compilers) → `docs/编译原理/` (e.g., [`PKU-Compilers.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/PKU-Compilers.md))

## Directory Structure and Bilingual Content

Each topic cluster follows a consistent file organization pattern that supports multilingual learners.

### File Naming Conventions

Every course page maintains parallel versions: a Chinese Markdown file (e.g., [`CS169.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS169.md)) and an English counterpart with the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) suffix (e.g., [`CS169.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS169.en.md)). The MkDocs `i18n` plugin automatically serves the appropriate version based on the user's language selection without requiring duplicate navigation entries in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml).

### Core Index Files

Several files drive the site-wide organization:

- **[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)** – Central navigation and site configuration
- **[`docs/index.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/docs/index.md)** – Front page (前言) rendered at the site root
- **`docs/使用指南.md`** – Usage guide explaining reading strategies
- **`docs/CS学习规划.md`** – Curated study roadmap cross-referencing topics

## Practical Example: Adding a New Course

Extending the guide requires creating Markdown content and registering it in the navigation configuration.

To add a new machine learning section to the CS self-learning guide, update [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml):

```yaml
nav:
  - 机器学习:
      - "Coursera: Machine Learning": "机器学习/ML.md"
      - "Stanford CS229: Machine Learning": "机器学习/CS229.md"

```

Place the new Markdown files in `docs/机器学习/` and rebuild the site:

```bash
mkdocs build

```

For bilingual content, create both `docs/深度学习/CS231.md` and `docs/深度学习/CS231.en.md`. The navigation points to the Chinese file, and the `i18n` plugin handles language switching automatically.

## Summary

- The **[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)** file defines the entire topic hierarchy through its `nav:` configuration
- Content is organized into topic clusters under **`docs/`**, with each cluster representing a CS sub-discipline like operating systems or computer architecture
- Bilingual support is implemented via **[`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md)** file suffixes handled by the `i18n` plugin
- Individual course pages contain rich metadata including difficulty ratings, estimated study time, and resource links
- Adding new topics only requires placing Markdown files in the appropriate subdirectory and updating the navigation configuration

## Frequently Asked Questions

### What file controls the topic organization in the CS Self-Learning Guide?

The **[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)** file at the repository root controls all topic organization. It declares the `nav:` structure that maps human-readable topic names to specific Markdown file paths under the `docs/` directory.

### How does the guide support multiple languages?

The guide uses MkDocs' **`i18n`** plugin to support bilingual content. Each page has a Chinese version (e.g., [`CS61B.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS61B.md)) and an English version (e.g., [`CS61B.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/CS61B.en.md)) in the same directory. The navigation configuration points to the Chinese file, and the plugin automatically serves the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) counterpart when users switch languages.

### Where are the course pages stored in the repository?

Course pages are stored as individual Markdown files within topic-specific subdirectories under `docs/`. For example, the CMU 15-445 database course resides at **`docs/数据库系统/15445.md`**, while MIT's Missing Semester is located at **`docs/编程入门/MIT-Missing-Semester.md`**.

### How can I contribute a new topic to the guide?

To contribute a new topic, create a Markdown file in the appropriate `docs/` subdirectory (such as `docs/新主题/course.md`), then add the corresponding entry to the `nav:` block in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml). If the content is bilingual, include both `.md` and [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) versions in the same folder.