How the CS Self-Learning Guide Is Organized by Topic

The CS Self-Learning Guide organizes content into topic-specific clusters defined in 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 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, 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 for MIT 18.01/18.02 Calculus)
• 数学进阶 (Advanced Mathematics) → docs/数学进阶/ (e.g., CS70.md for UCB CS70 Discrete Math)
• 编程入门 (Fundamental Programming) → docs/编程入门/ (e.g., MIT-Missing-Semester.md)
• 电子基础 (Fundamental Electronics) → docs/电子基础/ (e.g., EE16.md for EE16A&B)
• 数据结构与算法 (Data Structures and Algorithms) → docs/数据结构与算法/ (e.g., CS61B.md)
• 软件工程 (Software Engineering) → docs/软件工程/ (e.g., CS169.md for UCB CS169)
• 计算机系统基础 (Computer Systems Principles) → docs/计算机系统基础/ (e.g., CSAPP.md for CMU CSAPP)
• 体系结构 (Computer Architecture) → docs/体系结构/ (e.g., CS61C.md for UCB CS61C)
• 操作系统 (Operating Systems) → docs/操作系统/ (e.g., MIT6.S081.md)
• 计算机网络 (Computer Networking) → docs/计算机网络/ (e.g., topdown_ustc.md for the Top-Down Approach)
• 数据库系统 (Database Systems) → docs/数据库系统/ (e.g., 15445.md for CMU 15-445)
• 编译原理 (Compilers) → docs/编译原理/ (e.g., 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) and an English counterpart with the .en.md suffix (e.g., 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.

Core Index Files

Several files drive the site-wide organization:

• mkdocs.yml – Central navigation and site configuration
• 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:

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

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

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 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 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 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) and an English version (e.g., CS61B.en.md) in the same directory. The navigation configuration points to the Chinese file, and the plugin automatically serves the .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. If the content is bilingual, include both .md and .en.md versions in the same folder.

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