跳转至

John Class Manual 贡献指南

感谢您愿意为 John Class Manual 贡献内容！为了让本手册保持高质量与可读性，请在开始创作前花几分钟阅读以下准则。

本地预览环境

在提交 PR 前，请务必确保在本地渲染成功。下面提供了一个使用 conda 安装必要依赖并进行本地渲染的例子。

# 创建环境
conda create -n mkdoc python=3.10 -y
conda activate mkdoc

# 安装必要依赖
pip install mkdocs-material jieba mkdocs-minify-plugin

# 启动本地预览
mkdocs serve

运行后访问 http://127.0.0.1:8000 即可实时预览修改。

目录修改

这一部分 (Hopefully) 会逐渐自动化 —— But not yet

为了让 John Class Manual 更加的易读，我们在不同位置加入了一些索引，因此在修改条目时，也要对应的修改这些索引 / 目录以保持内容的一致性。主要的修改内容如下：

  1. 若想要增加任何文章，请在源代码根目录下的 mkdocs.yml 的相应位置加上文章的标题与文件位置，格式可以借鉴其他已有条目。另外，请注意新增文章文件名的一致性，因为虽然文件名不会作为标题出现，但会作为文章链接中的 tag

  2. 若完善了 课内课程 栏目中的文章或做了比较重大的修改，请进入课程对应的文件夹介绍 index.md，修改这一课程的介绍完成情况。

  3. 对于其他栏目的文章更新，同样需要在完成后进入 index.md，在有需要时根据文章内容进行更新

一、 基本要求与面向对象

  1. 受众定位：本手册的主要目标是新生扫盲，但也希望为其他年级的同学（如高年级课程、科研与就业指导）提供帮助。编辑时请假设该领域对读者是全新的知识，不预设读者具有预先知识或与您同等的能力。

  2. 知识衔接：对于预先知识较为繁杂的内容，请至少给出足以学习该知识的材料链接或基本的学习指引。

  3. 事实核实：所有写入手册的信息请在编辑前进行事实核实，并鼓励尽可能完整地提供参考资料列表与链接。

  4. 提交规范：提交 PR 时，请简要描述您的修改内容，并使用以下前缀修饰您的提交：

    • fix: 错误内容的修正。
    • feat: 新内容的添加。
    • chore: 文档结构、配置等其他杂项修改。

二、 语言风格

  1. 在非个人经验/日常部分，尽量克制包含（特别是非大众的）个人情感/好恶的语句，但不反对语言保持个人风格。如果有想要抒发个人感想/寄语的情况，可以注明，并建议与编写组其他成员预先交流。

  2. 请不要使用存在歧义、攻击性或小圈子特性的语句和词语。

    反例：切了、做题区、:Anon_angry:

  3. 请确保语言风格大体上的简练、通顺、平实、无语病，符合信息指引类文本的特性。

  4. 一定程度的中英文夹杂是可接受的，但为了清晰起见建议采用 中文 (英文) 形式。特别注意，请不要使用任何不必要的拼音缩写。

三、 Markdown 语法与排版规范

1. 结构与工具

  • 请使用标准 Markdown 编辑器（如 VSCode, Obsidian 等）编写正稿。

  • 图片：请统一放在 docs/assets/ 目录下。

  • 标题：正文从一级标题开始，可以没有序号。如有序号则按 一、二、三 -> 1, 2, 3 -> 1.1, 1.2, 2.1, 2.2 顺序进行。

2. Callout 标注块

支持使用 callout 标注块，但为避免令人困惑，限定使用以下四种，并请注意使用场景的合理性：

!!! abstract "摘要"
    用于概括全文要点

!!! note "笔记"
    用于补充背景知识或相关参考

!!! important "重要"
    用于强调重要信息

!!! quote "引用"
    用于引用他人观点

关于 callout 标注块是什么，请自行搜索 :)

3. MkDocs 语法适配

由于本框架使用 MkDocs Material，其部分语法（如上述标注块）与标准 Markdown 有差异。如果您不熟悉语法，可以先写草稿，然后利用以下 Prompt 让 AI 帮您转换：

Note

我是一份基于 MkDocs Material 框架文档的内容贡献者。请将以下 Markdown 草稿转换为带有 Material 专属语法的格式。要求如下： 1. 将草稿中的提示、警告、注意等情绪块，转换为对应的 Admonitions 语法，如 !!! tip, !!! warning，并注意内部文本的正确缩进。

  1. 若草稿中存在分类对比，请转换为 Content Tabs 语法，如 === 标签。

  2. 仅调整语法格式，绝对不要修改我原稿中的主观评价与客观信息。

四、 敏感内容申明

在本手册中，下述内容被定义为敏感信息： 1. 涉及特定实验室、课题组或企业的内部评价与主观经验陈述。 2. 含有具体同学或校友真实姓名、联系方式、学业数据等个人隐私的材料。 3. 任何形式的课程回忆版试卷、未公开考核资料及其相关解答。

在提交 PR 时，若涉及上述敏感信息或其他您认为不宜公开的内容，请务必向维护者声明，以便我们将该部分内容定向部署至受保护的闭源分支。

五、关于署名

关于署名，我们支持贡献者在文章中以自己喜欢的方式署名，但也尊重您保留隐私的意愿。因此，若您想要在文章中署名，请参考以下形式之一：

  1. 在文章一级标题下方，使用引言块注明，如： > 作者：[您的署名] (Class of 202X)
  2. 如果您希望通过署名进行交流，可以采用 Markdown 链接形式： > 作者：[[您的名字](您的 GitHub/个人主页链接)]

即使您不想在文章中署名，也建议以相同的形式注明写作日期，从而让读者更好的了解您提供信息的时效性

特别的，如果您的文章是与其他同学合作完成的，则可以考虑两种署名形式

  1. 若文章本身就是合作写作的，则直接在署名区一起署名即可

  2. 若文章本身是其中一位同学的文章，但您 (与其他编辑者) 想在里面进行少量评注或补充，可以以注释格式 + 署名评论的形式编辑，如:

xxxxx

Crykkkk: 这是一条评论

xxxxx