Course Documentation Template Structure in PKUFlyingPig/cs-self-learning

The repository uses a standardized bilingual Markdown template consisting of five mandatory sections—Course Identifier, Overview, Resources, Personal Summary, and Editorial Guidelines—to ensure consistent documentation across all courses.

The PKUFlyingPig/cs-self-learning repository maintains a strict course documentation template structure that contributors must follow when adding new courses. This scaffold exists in two parallel files—template.md for Chinese documentation and template.en.md for English—both enforcing identical logical layouts through clearly named sections.

Core Template Files

The documentation standard is defined in two root-level files:

• template.md – The Chinese version requiring specific Simplified Chinese headings and bullet labels
• template.en.md – The English counterpart using equivalent English terminology

Both templates share the same sectional hierarchy, differing only in language-specific labels and the presence of an additional "Remarks" section in the Chinese version that addresses mixed Chinese-English typography rules.

Anatomy of the Course Documentation Template

The template enforces a five-section structure that every course submission must follow.

Header – Course Identifier

The document must begin with a single H1 heading containing the course code and official name:

# 课号：课程名称

In template.en.md, this becomes:

# Course Code: Course Name

This header serves as the canonical identifier for the course entry.

Course Overview Section

The second section uses an H2 heading—## 课程简介 in Chinese or ## Descriptions in English—followed by a standardized bullet list capturing essential metadata:

• 所属大学 / Offered by: The institution providing the course
• 先修要求 / Prerequisites: Required background knowledge
• 编程语言 / Programming Languages: Primary languages used
• 课程难度 / Difficulty: Visual rating using star emojis (🌟🌟🌟)
• 预计学时 / Class Hour: Estimated time commitment

Below the bullet list, authors insert an HTML comment block (lines 11–17 in both template files) containing guidance on writing the descriptive paragraph. This hidden instruction reminds contributors to cover course coverage, unique aspects, personal experience, and potential pitfalls.

Course Resources Section

The third section—## 课程资源 or ## Course Resources—requires a bullet list linking to official materials:

• 课程网站 / Course Website: Official course URL
• 课程视频 / Recordings: Lecture video links
• 课程教材 / Textbooks: Required or recommended reading
• 课程作业 / Assignments: Link to labs or homework

Personal Resource Summary

The fourth section—## 资源汇总 or ## Personal Resources—contains a placeholder for the contributor's personal repository:

@XXX 在学习这门课中用到的所有资源和作业实现都汇总在 [user/repo - GitHub](https://github.com/user/repo) 中。

Authors replace @XXX with their GitHub handle and update the repository link to point to their collected assets and solutions.

Editorial Guidelines (Chinese Only)

The Chinese template.md includes a final ## 备注 section containing two critical references:

• Markdown Rules – Linking to markdownlint documentation
• Markdown 简体中文与西文混排要点 – Guidelines for Chinese-English mixed typography

The section concludes with the instruction 正文中请删除该节。, reminding authors to delete this editorial block before submission.

Practical Implementation Example

Below is a complete filled example demonstrating how placeholders translate to actual content:

# CS61C：计算机体系结构

## 课程简介

- 所属大学：加州大学伯克利分校
- 先修要求：CS61A、CS61B
- 编程语言：C、Python
- 课程难度：🌟🌟🌟🌟
- 预计学时：12 周

<!--
本课程深入讲解现代计算机体系结构，包括流水线、缓存、并行计算等内容。相比其他体系结构课，它提供了大量的硬件实验和项目，实现了对理论的真实落地。个人在完成项目时体会到位移操作的细节难度，需要提前熟悉 C 语言的低层特性。自学时需要注意实验环境的搭建以及代码调试的细节，尤其是硬件仿真部分容易卡壳。
-->

## 课程资源

- 课程网站：https://cs61c.org/
- 课程视频：https://www.bilibili.com/video/CS61C
- 课程教材：《Computer Architecture: A Quantitative Approach》
- 课程作业：https://cs61c.org/fa22/labs/

## 资源汇总

@ZhangSan 在学习这门课中用到的所有资源和作业实现都汇总在 [ZhangSan/cs61c - GitHub](https://github.com/ZhangSan/cs61c) 中。

## 备注

编写文档时尽量遵守 [Markdown Rules][md_rules] 与 [Markdown 简体中文与西文混排要点][cn_en_mixed_typography]，前者可以通过 VS Code 插件 *markdownlint* 提示并处理。

[md_rules]: https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
[cn_en_mixed_typography]: https://github.com/selfteaching/markdown-writing-with-mixed-cn-en

正文中请删除该节。

Summary

• The course documentation template structure enforces consistency through template.md (Chinese) and template.en.md (English)
• Five mandatory sections ensure comprehensive coverage: Course Identifier, Overview with metadata bullets, Resources, Personal Repository links, and Editorial Guidelines
• The template uses standardized bullet labels for university, prerequisites, programming languages, difficulty ratings, and time estimates
• HTML comment blocks provide invisible writing guidance for the descriptive content
• Contributors must delete the Remarks section before final submission, which contains links to markdownlint rules and Chinese-English typography standards

Frequently Asked Questions

What files define the course documentation template structure?

The structure is defined in template.md (Chinese) and template.en.md (English) located in the repository root. These files provide the scaffold that all course submissions must follow.

How does the Chinese template differ from the English version?

Both share identical logical layouts, but the Chinese template.md includes an additional ## 备注 section containing links to Markdown linting rules and Chinese-English mixed typography guidelines. This section is absent from template.en.md.

What information is required in the Course Overview section?

Authors must provide five specific data points: the offering university, prerequisites, programming languages used, a difficulty rating using star emojis (🌟), and estimated class hours. This must be formatted as a bullet list followed by a descriptive paragraph inside an HTML comment template.

Are there specific formatting rules for contributors?

Yes. Contributors must follow markdownlint rules and, for Chinese submissions, adhere to the Chinese-English mixed typography guide. The template explicitly requires deletion of the Remarks section before submission, as indicated by the cleanup prompt 正文中请删除该节。

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