# 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:

```text
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](https://squidfundamentals.com/mkdocs-material/customization/) mechanism. The `comments.html` partial injects the Giscus discussion widget into every page.

### Component inventory

| Component | Path | Role |
|---|---|---|
| MkDocs configuration | `mkdocs.yml` | Defines site structure, navigation, theme, plugins, i18n |
| Python dependencies | `requirements.txt` | Pins MkDocs Material and plugin versions |
| Course content | `docs/{topic}/*.md` | Chinese course pages |
| English translations | `docs/{topic}/*.en.md` | English course page variants |
| Theme overrides | `overrides/` | Custom partials (Giscus comments) |
| Static assets | `docs/images/` | Favicon, logo, mobile icon, sponsor image |
| Custom domain | `docs/CNAME` | Maps to `csdiy.wiki` |
| Templates | `template.md`, `template.en.md` | Standard format for new course entries |

### Technology stack

| Layer | Technology | Version |
|---|---|---|
| Static site generator | MkDocs | (via mkdocs-material) |
| Theme | Material for MkDocs | 9.5.2 |
| Internationalization | mkdocs-static-i18n | 1.2.0 |
| Search | MkDocs built-in | Chinese + English |
| Minification | mkdocs-minify-plugin | 0.7.1 |
| Git dates | mkdocs-git-revision-date-plugin | latest |
| Link behavior | mkdocs-open-in-new-tab | 1.0.8 |
| Template engine | Jinja2 | 3.1.2 |
| Comments | Giscus | External (GitHub Discussions) |
| Analytics | Google Analytics | Property `G-KJB4RXSKZG` |
| Hosting | GitHub Pages | Custom domain: `csdiy.wiki` |

## 2. System Requirements

### Build requirements

| Requirement | Detail |
|---|---|
| Python | 3.8+ (any version supporting the pinned dependencies) |
| pip | For installing dependencies from `requirements.txt` |
| Git | Required by `mkdocs-git-revision-date-plugin` (must be a git repo) |
| Disk space | ~50 MB for dependencies, ~20 MB for the built site |

### 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

| Key | Value | Purpose |
|---|---|---|
| `site_name` | `CS自学指南` | Browser title and header text |
| `site_url` | `https://csdiy.wiki/` | Canonical URL for SEO and sitemap |
| `site_author` | `PKUFlyingPig` | Author metadata |
| `site_description` | `CS自学指南` | Meta description for search engines |
| `repo_name` | `cs-self-learning` | GitHub repo label shown in header |
| `repo_url` | `https://github.com/pkuflyingpig/cs-self-learning/` | Link to source repository |
| `copyright` | `Copyright © 2021-present PKUFlyingPig` | Footer copyright notice |

#### Theme configuration

```yaml
theme:
  name: material
  language: zh
  custom_dir: overrides
```

| Setting | Value | Effect |
|---|---|---|
| `name` | `material` | Uses Material for MkDocs theme |
| `language` | `zh` | Default language is Chinese |
| `custom_dir` | `overrides` | Theme override directory for custom partials |
| `favicon` | `images/favicon.ico` | Browser tab icon |
| `apple-touch-icon-precomposed` | `images/mobile_icon.png` | iOS home screen icon |
| `static_templates` | `[404.html]` | Custom 404 page |
| `include_search_page` | `false` | Search is inline, not a separate page |
| `search_index_only` | `true` | Builds search index without dedicated search page |

#### Theme features

| Feature | Purpose |
|---|---|
| `header.autohide` | Header hides on scroll-down, reappears on scroll-up |
| `navigation.tracking` | URL updates with scroll position |
| `navigation.top` | "Back to top" button appears on scroll |
| `search.highlight` | Search terms are highlighted in results |
| `search.share` | Search results can be shared via URL |
| `search.suggest` | Autocomplete suggestions in search |
| `content.code.annotate` | Code blocks support annotation markers |

#### Color palette

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

| Mode | Scheme | Primary Color | Accent Color | Toggle Icon |
|---|---|---|---|---|
| Light | `default` | Light Blue | Deep Purple | `material/weather-sunny` |
| Dark | `slate` | Cyan | Deep Purple | `material/weather-night` |

#### Typography

| Setting | Font | Usage |
|---|---|---|
| `text` | Roboto Slab | Body text (serif slab) |
| `code` | Roboto Mono | Code blocks and inline code |

#### Markdown extensions

| Extension | Purpose |
|---|---|
| `attr_list` | Add HTML attributes to markdown elements |
| `md_in_html` | Render markdown inside HTML blocks |
| `footnotes` | Support `[^1]` footnote syntax |

> [!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

| Plugin | Configuration | Purpose |
|---|---|---|
| `i18n` | Two locales: `zh` (default), `en` | Bilingual site generation |
| `search` | Languages: `zh`, `en` | Full-text search across both languages |
| `git-revision-date` | (no config) | Shows last-modified date per page |
| `minify` | `minify_html: true` | Minifies HTML output for performance |
| `open-in-new-tab` | (no config) | External links open in new tabs |

#### i18n plugin configuration

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

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

| Key | Value | Purpose |
|---|---|---|
| `extra.social[0]` | GitHub icon → repo URL | Social link in footer |
| `extra.analytics.provider` | `google` | Google Analytics integration |
| `extra.analytics.property` | `G-KJB4RXSKZG` | GA4 measurement ID |

#### 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

```text
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
```

| Dependency | Pinned | Notes |
|---|---|---|
| `mkdocs-material` | `==9.5.2` | Core theme; major versions can have breaking changes |
| `mkdocs-minify-plugin` | `==0.7.1` | HTML minification |
| `mkdocs-git-revision-date-plugin` | unpinned | Shows last-modified dates |
| `jinja2` | `==3.1.2` | Template engine; pinned for compatibility |
| `mkdocs-static-i18n` | `==1.2.0` | Bilingual support |
| `mkdocs-open-in-new-tab` | `==1.0.8` | External link behavior |

> [!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

```bash
# 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
```

```text
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

```bash
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.

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

```bash
# 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:

| Record Type | Name | Value |
|---|---|---|
| A | `@` | GitHub Pages IPs (185.199.108-111.153) |
| CNAME | `www` | `pkuflyingpig.github.io` |

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

```bash
# 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

| Task | Frequency | How |
|---|---|---|
| Check broken links | Monthly | `mkdocs build --strict` flags missing internal references |
| Verify course URLs | Quarterly | Manual spot-check of external links (courses move between semesters) |
| Update translations | Ongoing | Community PRs add English translations for Chinese-only pages |
| Review GitHub issues | Weekly | Triage new course suggestions, bug reports, and content requests |

## 6. Performance

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

| Optimization | Implementation |
|---|---|
| HTML minification | `mkdocs-minify-plugin` compresses all generated HTML |
| Search index | `search_index_only: true` avoids generating a separate search page |
| Image assets | Minimal — only 5 images in `docs/images/` (favicon, logo, icons, sponsor) |
| CDN | GitHub Pages provides global CDN distribution |

### 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:

| Vector | Risk | Mitigation |
|---|---|---|
| XSS via content | Low | MkDocs sanitizes markdown rendering; no user-submitted content at build time |
| Dependency supply chain | Medium | Pin dependency versions in `requirements.txt`; audit before updating |
| DNS hijacking | Low | Use DNSSEC if registrar supports it; monitor CNAME records |
| Comment spam (Giscus) | Low | Giscus requires GitHub authentication; moderation via GitHub Discussions |
| Analytics data exposure | Low | GA4 property `G-KJB4RXSKZG` is public by nature (client-side tracking) |

> [!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

```text
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

| Pattern | Meaning | Example |
|---|---|---|
| `{Code}.md` | Chinese course page | `CS61A.md` |
| `{Code}.en.md` | English course page | `CS61A.en.md` |
| `{topic}/` | Topic folder (Chinese name) | `数据结构与算法/` |
| `template.md` | Page template (repo root) | Standard format for new entries |

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

| System | Integration | Configuration |
|---|---|---|
| **GitHub Pages** | Static site hosting | `docs/CNAME` → `csdiy.wiki` |
| **GitHub Discussions** | Comment system (Giscus) | `overrides/partials/comments.html` |
| **Google Analytics** | Traffic tracking | `extra.analytics.property: G-KJB4RXSKZG` |
| **GitHub Repository** | Source control, issue tracking, PRs | `repo_url` in `mkdocs.yml` |
| **Git history** | Per-page last-modified dates | `mkdocs-git-revision-date-plugin` |

---

_Generated May 2026 from PKUFlyingPig/cs-self-learning at 3ec3100. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._