CS Self-Learning Guide (CS自学指南) — Administrator & Developer Guide

1. Architecture Overview

CS自学指南 is a static documentation site built with MkDocs Material. The entire project is a content repository — there is no application server, database, or API. The architecture is:

GitHub Repository (PKUFlyingPig/cs-self-learning)
  ├── mkdocs.yml          ← Site configuration (nav, theme, plugins, i18n)
  ├── requirements.txt    ← Python dependencies
  ├── template.md         ← Course page template (Chinese)
  ├── template.en.md      ← Course page template (English)
  ├── overrides/          ← MkDocs Material theme overrides
  │   └── partials/
  │       └── comments.html  ← Giscus comment widget integration
  └── docs/               ← All content (283 files)
      ├── index.md / index.en.md        ← Foreword
      ├── 使用指南.md / .en.md           ← How to use the guide
      ├── CS学习规划.md / .en.md         ← Learning roadmap
      ├── 好书推荐.md                    ← Book recommendations
      ├── 后记.md                        ← Postscript
      ├── CNAME                          ← Custom domain (csdiy.wiki)
      ├── images/                        ← Static assets
      └── {topic}/                       ← 25 topic folders, each with course .md files
          └── {CourseCode}.md / .en.md

Note

The overrides/ directory uses MkDocs Material's custom directory mechanism. The comments.html partial injects the Giscus discussion widget into every page.

Component inventory

Technology stack

2. System Requirements

Build requirements

Runtime (production)

The built site is static HTML — it requires only a web server or hosting platform (GitHub Pages, Netlify, Vercel, or any static file server).

3. Configuration Reference

mkdocs.yml — Complete breakdown

The single configuration file controls all aspects of the site. Below is every configuration section with its purpose and values.

Site metadata

Theme configuration

theme:
  name: material
  language: zh
  custom_dir: overrides

Theme features

Color palette

The site supports automatic light/dark mode switching based on system preference:

Typography

Markdown extensions

Important

These three extensions are required for the content to render correctly. Adding extensions like admonition, pymdownx.superfences, or toc is safe but removing any of the three above will break existing content that relies on them.

Plugins

i18n plugin configuration

The mkdocs-static-i18n plugin is the most complex configuration block. It defines two locales and provides navigation label translations:

plugins:
  - i18n:
      languages:
        - locale: zh
          default: true
          name: 简体中文
          build: true
        - locale: en
          name: English
          build: true
          site_name: csdiy.wiki
          nav_translations:
            前言: Foreword
            如何使用这本书: How To Use The Book
            # ... (50+ translations)

Note

The English locale overrides site_name to csdiy.wiki (instead of the Chinese CS自学指南). Every navigation label in the nav: section has a corresponding translation entry. When adding new navigation items, you must add the translation or the English site will show Chinese labels.

The i18n plugin works by file convention: page.md is the Chinese version, page.en.md is the English version. Both must exist for a page to appear in both language builds.

Extra configuration

Navigation (nav:)

The nav: section defines the complete site structure as a YAML tree. It contains 25 top-level sections with 100+ course entries. Each entry maps a display title to a file path relative to docs/.

Warning

The nav: section is the single most critical part of mkdocs.yml. An indentation error or missing file reference will break the entire site build. Always validate with mkdocs build --strict after editing navigation.

requirements.txt — Dependency pins

mkdocs-material==9.5.2
mkdocs-minify-plugin==0.7.1
mkdocs-git-revision-date-plugin
jinja2==3.1.2
mkdocs-static-i18n==1.2.0
mkdocs-open-in-new-tab==1.0.8

Caution

mkdocs-git-revision-date-plugin is unpinned. This means builds may break if a new release introduces incompatibilities. Consider pinning it after testing with a specific version.

docs/CNAME

Contains the custom domain csdiy.wiki for GitHub Pages. This file must remain in docs/ (not the repo root) because MkDocs copies docs/ contents to the build output, and GitHub Pages reads CNAME from the deploy root.

4. Deployment & Building

Local development

# Clone the repository
git clone https://github.com/PKUFlyingPig/cs-self-learning.git
cd cs-self-learning

# Install dependencies
pip install -r requirements.txt

# Start the development server
mkdocs serve

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in X.XX seconds
INFO    -  [I 12:00:00 server:335] Serving on http://127.0.0.1:8000

The dev server watches for file changes and live-reloads the browser.

Tip

Use mkdocs serve --dirtyreload for faster rebuilds during content editing — it only rebuilds changed pages instead of the entire site.

Production build

mkdocs build --strict

This generates the static site in site/ (default output directory). The --strict flag treats warnings as errors, catching broken links and missing files.

INFO    -  Building documentation...
INFO    -  [i18n] Building 'zh' locale
INFO    -  [i18n] Building 'en' locale
INFO    -  Documentation built in X.XX seconds

Deployment to GitHub Pages

The site is hosted on GitHub Pages. Deployment options:

# Option 1: MkDocs built-in deploy (pushes to gh-pages branch)
mkdocs gh-deploy --force

# Option 2: GitHub Actions (if configured)
# Push to main branch → CI builds and deploys automatically

Important

The docs/CNAME file ensures the custom domain csdiy.wiki persists across deployments. If this file is accidentally removed, the site will revert to pkuflyingpig.github.io/cs-self-learning/.

DNS configuration

The custom domain csdiy.wiki must have DNS records pointing to GitHub Pages:

5. Operations

Adding a new course

1. Choose the appropriate topic folder under docs/
2. Create {CourseCode}.md (Chinese) using template.md as a base
3. Create {CourseCode}.en.md (English) using template.en.md as a base
4. Add the navigation entry to mkdocs.yml under the correct section:

   - "University CourseCode: Course Title": "topic/CourseCode.md"
   

5. If the topic is new, add a nav_translations entry in the i18n plugin config
6. Test with mkdocs build --strict to verify no broken references
7. Submit a pull request

Tip

Keep the course code in the filename (e.g., CS61A.md, not intro-to-cs.md). This matches the established convention across all 100+ course pages and makes files easy to locate.

Adding a new topic section

1. Create a new folder under docs/ with the Chinese topic name
2. Add course files to the folder
3. Add the section to mkdocs.yml nav: with all course entries
4. Add the Chinese-to-English topic name translation in nav_translations
5. Rebuild and verify both language versions render correctly

Updating dependencies

# Check for available updates
pip list --outdated

# Update a specific package
pip install mkdocs-material==X.Y.Z

# Update requirements.txt
pip freeze | grep -i mkdocs > requirements.txt

Warning

Always test the full build after updating mkdocs-material. Major version bumps (e.g., 9.x → 10.x) frequently change configuration syntax, theme features, and plugin APIs. Pin to exact versions in production.

Content maintenance

6. Performance

The site is static HTML — performance is primarily a function of the hosting CDN and asset optimization.

Build performance

With 283 files and two language builds, the full site build takes approximately 30-60 seconds depending on hardware. The git-revision-date plugin adds overhead because it queries git history for every file.

Tip

During local development, mkdocs serve --dirtyreload skips unchanged pages and can reduce rebuild time to under 2 seconds for single-file edits.

7. Security

Threat model

As a static documentation site with no backend, the attack surface is minimal:

Warning

The mkdocs-git-revision-date-plugin is unpinned in requirements.txt. A compromised release could execute arbitrary code during the build process. Pin it to a specific version and verify checksums in CI.

Content integrity

All content changes go through GitHub pull requests. The repository history provides a complete audit trail. There is no dynamic content injection — what's in the repo is what gets served.

8. Developer Internals

Repository structure

cs-self-learning/
├── .editorconfig          ← Editor settings (indentation, charset, line endings)
├── .gitignore             ← Excludes site/, venv, __pycache__, etc.
├── LICENSE                ← Project license
├── README.md              ← Repository description and quick links
├── mkdocs.yml             ← Central configuration (1 file, ~306 lines)
├── requirements.txt       ← Python dependency pins (6 packages)
├── template.md            ← Course page template (Chinese)
├── template.en.md         ← Course page template (English)
├── overrides/
│   └── partials/
│       └── comments.html  ← Giscus comment integration (HTML partial)
└── docs/
    ├── CNAME              ← Custom domain for GitHub Pages
    ├── index.md           ← Site homepage / foreword
    ├── 使用指南.md         ← How to use the guide
    ├── CS学习规划.md       ← Learning roadmap
    ├── 好书推荐.md         ← Book recommendations
    ├── 后记.md             ← Postscript
    ├── images/            ← Static assets (5 files)
    └── {25 topic folders}/
        └── {CourseCode}.md + {CourseCode}.en.md

File naming conventions

The i18n plugin uses the .en.md suffix convention to associate English pages with their Chinese counterparts. Both files must have the same base name.

Giscus integration

The comment system is implemented via overrides/partials/comments.html. This HTML partial is injected into every page by MkDocs Material's template system. Giscus maps each page to a GitHub Discussion thread based on the page URL.

Known issue: Some pages map to incorrect Discussion threads. See #847 — the Foreword (前言) page's Giscus comments incorrectly load the CS162 discussion.

Content organization patterns

Bilingual parity: Every content page should have both .md and .en.md versions. Some pages may exist only in Chinese — the i18n plugin handles this gracefully by falling back to the default locale's content.

Topic depth: Topic folders are flat (one level) except for two cases:

• 编程入门/ has language sub-folders (Python/, C/, cpp/, Java/, Rust/, Functional/)
• 深度生成模型/ has a 大语言模型/ (Large Language Models) sub-folder

Navigation mirrors filesystem: The nav: tree in mkdocs.yml directly maps to the folder structure. Reordering courses in the nav changes only display order, not file locations.

How the i18n system works

The mkdocs-static-i18n plugin version 1.2.0 performs two full builds of the site — one per locale. For the Chinese build, it uses {name}.md files. For the English build, it uses {name}.en.md files, falling back to {name}.md if no English version exists.

Navigation labels come from nav: entries (Chinese) and are translated via the nav_translations mapping in the English locale configuration. The result is two complete, independent site builds served under the same domain with a language toggle.

Note

The nav_translations dictionary contains 50+ entries. When adding a new section to nav:, the corresponding English translation must be added here or the English site will display the Chinese label.

Testing strategy

There is no automated test suite. Quality assurance relies on:

1. mkdocs build --strict — catches broken internal links, missing files, and YAML errors
2. Manual review — pull request reviewers check content accuracy and formatting
3. Community feedback — readers report issues via GitHub Issues and Giscus comments

Tip

Consider adding a CI workflow that runs mkdocs build --strict on every pull request to catch configuration and linking errors before merge.

Potential improvements

Based on the current codebase and community issues:

1. Pin mkdocs-git-revision-date-plugin — currently unpinned, creates reproducibility and security risk
2. Add CI/CD pipeline — automate mkdocs build --strict on PRs and mkdocs gh-deploy on merge to main
3. Fix Giscus page mapping — investigate and correct the comment-to-page mapping issue (#847)
4. Add link checker — integrate a tool like linkchecker or lychee to periodically validate external course URLs
5. Expand English coverage — many course pages exist only in Chinese; a translation tracker would help prioritize
6. Consider mkdocs-git-revision-date-localized-plugin — the -localized variant offers more date format options and is more actively maintained

9. Integration Points