# 编辑者须知

LLMS index: [llms.txt](/wikis/llms.txt)

---

# 编辑者须知（草案）

## 贡献方式

文档目前存储于 [GitHub Repo](https://github.com/SAST-skill-docers/sast-skill-docs) 上，使用 GitHub Pages 部署成了目前的技能引导文档网站。如果您有意贡献到本项目，请您：

+ 检查自己想要贡献的部分是否在 Repo 的 Issue 中已经提出，若已经提出则不必重复 PR。
+ 确认自己想要贡献的部分暂未在 Issue 中提出时，提出 Issue 表明需要贡献哪一部分内容。
+ 仔细阅读本编辑者须知下的编辑要求，不符合下述编辑要求的贡献，审核团队可能会拒绝合并并要求您修改。
+ 将文档仓库 Fork 到个人账户。
+ 在本地对个人仓库的文档进行修改后进行 Commit。
+ 提请 Pull Request，审核团队会尽快审核您的贡献内容，审核完毕后会关闭您提出的 Issue。

## 本地构建

在提请 PR 之前，您可以首先在本地构建文档并在浏览器中浏览，以确定自己的文档渲染正确且符合格式要求。

构建之前，首先通过下述命令确保您的环境具有 Python 和 pip：

```bash
python --version
pip --version
```

随后进入 Clone 到本地的仓库的根目录，安装 Python 依赖：

```bash
pip install -r requirements.txt
```

随后运行：

```bash
mkdocs serve
```

应当可以看到类似输出信息：

```bash
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 8.75 seconds
INFO     -  [17:16:02] Serving on http://127.0.0.1:8000/
```

这样就可以通过浏览器访问 `http://127.0.0.1:8000/` 查看本地构建的文档了。

## 准确性

请记住，编写者有义务确保贡献的文档没有事实错误。

如果新贡献的文档超出了审核团队的专业知识范围，审核团队需要寻求其他专业人员的帮助，可能会导致审核周期延长。

## 文章立场

我们希望编辑者尽量站在客观的角度、以**初学者的视角**编写引导文档。也就是说，只要阅读者具有了文档之中要求的前置知识，就应当能够无障碍阅读学习文档内容。

> [!NOTE]
> **示例**
>
>
> 例如，对于前置知识中已给出，而不需要详细讲解的知识，可以在前置知识部分声明之后使用类似如下的表述：
>
> **TypeScript 语言之中的类类似于 ES6 标准中 JavaScript 语言之中的类，故此处仅给出样例程序而不进行详细讲解。不过需要注意的是，TypeScript 语言之中的类允许声明类成员和方法的访问权限。**
>
> 对于其他文档中已给出，而不需要详细讲解的知识，也可以采用这类表述，然后在对应前置知识的位置进行明显标注，并设置跳转链接。
>
> 另一方面，我们不希望编辑者采用类似如下的表述：
>
> **读者应当已经在《面向对象程序设计基础》课程之中学习过类似知识，这里不进行表述。**
>
> 这类表述问题在于其引用的资源（课程资源）并不能自由获取，这类表述可能造成读者学习的障碍。解决方式是编辑者在文档中做出详细解释或在资源链接部分给出相关资料。
同时，作为计算机系学生科协的一份技能引导文档，我们与网络上的各种技能教程最大的区别在于，我们的目标读者是计算机类与计算机系的同学。编辑者可以尝试从自身的学习经历出发，省略部分在课程教授中基础而不必要的介绍（使用相关网络资料链接替代），并告知读者如何在课程中，在科研中，在实习中将展示的知识应用到实践当中。

## 文章架构

一份完整的技能引导文档至少应当包含以下部分：

- **前置知识**部分。在这一部分，编辑者需要指明阅读这一份文档所需要的所有前置知识。所有的前置知识使用无序列表给出。

- **学习路径**部分。该部分可选，推荐涉及较广知识面的文档包含这一部分。在这一部分，编辑者需要说明有不同知识需求的读者本文档应该按照何种顺序阅读、学习。

- **知识讲解**部分。在这一部分，编辑者需要对知识点有条理地进行讲解，并且适当地引用外部资源作为辅助。

- **后续拓展**部分。在这一部分，编辑者可以指出学习完这一部分知识后可以进一步学习的领域，或者可以应用这些知识的课程。所有的后续拓展学习内容使用无序列表给出。

- **资源链接**部分。在这一部分，编辑者需要将文档中所引用的资源列出，编辑者有责任保证资源有效、可访问。部分用于知识拓展的资源也可以放置在这一部分。此部分在罗列链接之外，应当具体说明每个链接中大致有什么内容。

## 文档存储

+ 文件名请全部使用小写，分隔符请使用 `-`。
+ 文件应视主题，放于对应的分类目录下。新建的文件需要在 `mkdocs.yml` 中声明，以调整文档的层级结构。
    + 若多个文档同时归属某个大主题，则可为该大主题新建文件夹存储。
+ 关于文档中需要展示的图片，请存储到 `/static` 下与文档相对 `/docs` 目录同名的文件夹中，并命名为 `内容概要.文件扩展名`。如 `/docs/basic/git.md` 的图片文件请存储为 `/static/basic/git/logo.png`。

## 文章格式

> [!CAUTION]
> **换行符**
>
>
> 换行符的问题尤其重要，以至于需要在文章格式部分的一开始就指出这个问题。
>
> 本文档的自动化贡献计算插件基于 Git 的 Commit 行数，而修改换行符也会计算到 Commit 修改之中，所以换行符会影响到文档最后的贡献度 Credit。
>
> 对于已存在的文章，不能更改其未修改的行的换行符，否则 Pull Request 将会被直接关闭；
>
> 对于新建立的文档，可以使用默认换行符。
### 标题与小标题

+ 文章中应仅存在一个**一级标题**，以概括文章的主题。
+ 文章采用**二级标题**作为分节符，如【前置知识】【后续拓展】【资源链接】均可以作为一个小节。文章的主题内容应分为多个小节。
+ **三级标题**应起到在一个小节中分隔不同讨论内容的作用。如二级标题 `JavaScript 的函数` 下，三级标题可以包含 `函数声明与调用`、`回调模式`、`闭包` 等等整体上不相交的内容。
+ 不要滥用标题，我们推荐至多使用至三级标题，四级及以上标题可以使用加粗、无序列表代替。滥用标题会使得文章的目录结构变复杂，也会在一定程度上影响读者对所学习知识的结构的整体性把握。如果想强调内容，使用 `**强调内容**`。
+ 标题中应当尽量不出现代码块。

### 排版要求

我们并不严格要求文档的排版风格，但编辑者应当尽可能遵守以下基本的文档行文要求。

**正确使用标点符号**

+ 正确使用**全角**标点符号与**半角**标点符号。汉语请使用全角符号，英语请使用半角符号。
+ 请在每句话的末尾添加**句号**。
+ 正确使用**括号**。括号在句中表示对句中前一个元素的解释说明，如 `语法糖（英语：Syntactic sugar）`。括号在句外表示对前面整个句子的解释说明。
+ 正确使用**分号**，可以使得行文结构更加清晰。

**正确进行中文排版**

+ 中英文之间、中文和数字之间需要增加空格，数字和单位之间不需要增加空格。
+ 行文中正文与超链接之间需要增加空格。
+ 全角字符和其他字符之间不加空格。
+ 专有名词使用正确的大小写。如使用缩写，则该缩写应已成为业界标准。

### 使用图片

图片是重要的辅助说明的工具，但是由于 Markdown 的图片工具并不完善，所以请注意以下要求。

> [!CAUTION]
> **Markdown 的图片尺寸问题**
>
>
> Markdown 没有控制图片尺寸的命令，其默认缩放图片以填满宽度。为了保证美观性和阅读体验，类似 Logo 等并不需要占满宽度的图片，请使用 HTML 标签控制其尺寸。例如：
>
> ```html
> <center>
>     <img src="https://i.loli.net/2021/10/10/NHZOsPCBmazyWjh.png" height="20%" width="20%">
> </center>
> ```
> [!CAUTION]
> **带下标的图片**
>
>
> Markdown 并不支持带下标的图片，所以请使用 HTML 标签。推荐使用：
>
> ```html
> <center>
>     <img src="https://i.loli.net/2021/09/28/Ti2VR4DtbgcdlkM.png" />
>     <img src="https://i.loli.net/2021/09/28/Dvpkbd7KjLTH2yl.png" />
>     <p style="text-align: center; margin-top: 0px; color: gray; padding: 0px">脚本文件的例子</p>
> </center>
> ```
### 使用折叠框

正文的语言风格尽量正式，感悟、思考、启发、前言、补充性内容、Checkpoint 等非正文内容尽量纳入折叠框之中。

附：[折叠框使用教程](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)

### 使用公式

当行文遇到数学公式时，使用行内公式 `$a \times b$` 和行间公式 `
```math
...
```
` 来进行数学形式的讲解，而不要使用 x^2 这种影响阅读美观程度的写法。正确示例：\(x^2\)。

附：[Mathjax 代码教程](https://oysz2016.github.io/post/8611e6fb.html)

**使用数学公式的注意事项**

+ 部分常用函数，如三角函数、对数函数等的 Roman 体符号已经内置于 LaTeX 中。如余弦函数应当使用 `$\cos$` 表示，渲染为 \(\cos\)。而不应当使用 `$cos$` 表示，渲染为 \(cos\)。
+ 渲染 Roman 体（正体）粗体请使用 `$\mathbf{}$`，如 \(\mathbf{a}\)。渲染 Italic 体（斜体）粗体请使用 `$\boldsymbol{a}$`，如 \(\boldsymbol{a}\)。请不要混淆两者。
+ 行内公式渲染分数时，请使用 `$\dfrac{}{}$`，如 \(\dfrac{1}{2}\)。而不应使用 `$\frac{}{}$`，如 \(\frac{1}{2}\)。
+ 行内公式应尽力避免求和、求积、积分等巨运算符，即 \(\sum\)、\(\int\) 等运算符。
+ 省略号请使用 `$\cdots$`，如 \(a_1, a_2, \cdots, a_n\)。而不应使用 `$...$`，如 \(a_1, a_2, ..., a_n\)。
+ 注意区分数学语言与程序设计语言。请不要在公式块内使用双等号 \(==\) 乃至三等号 \(===\) 表示两个量相等，请使用数学语言中的单等号 \(=\)，如 \(a = b\)。此外，请不要使用中括号连缀表达高维数组，如 \(a[i][j][k]\)，请使用函数表示，如 \(f(i, j, k)\)。
+ 特殊集合（如自然数集、实数集）的字体请使用 `$\mathbb{}$`，如 \(\mathbb{R}\)、\(\mathbb{N}\)。
+ 括号内为分式等内容时，请使用自适应高度括号 `$\left(\right)$`，如 \(\left(\dfrac{1}{2}\right)^n\)。请不要直接使用 `$()$`，如 \((\dfrac{1}{2})^n\)。
+ 公式内请不要出现汉字，出现英文单词时请使用正体。

### 使用代码块

代码块在本技能引导文档中起到了举足轻重的地位。

我们统一规定，行内代码使用 `` ` `` 包裹。行间代码使用 ```` ``` ```` 包裹并在起始的三个反引号后标记代码的语言，例如：

````markdown
```cpp
#include <iostream>
using namespace std;
int main() {
    cout << "Hello World";
    return 0;
}
```
````

**行内代码和正文的区分**

+ 推荐将文件名、文件路径等使用行内代码表示。

**推荐的代码风格**

+ 变量使用驼峰命名法、下划线命名法等均可，但需要尽量保证同一篇文档内命名风格统一。
+ 下列代码风格惯例以 C++ 语言为例：
    + 大括号换行与不换行均可，但需要保证同一篇文档内格式统一。不换行时，其与左侧的右括号之间应当有一个空格。
    + 关键字 `if`、`for` 等与后续左括号之间应当有一个空格。
    + 运算符 `+`、`-` 等与左右操作数之间应当各有一个空格，运算符 `.`、`->` 两侧均不应当有空格，逗号 `,` 左侧不应当有空格而右侧应当有空格。
    + 行内注释起始标记 `//` 与注释文字间应当有一个空格。
    + 使用 2 个空格或者 4 个空格进行缩进均可，但需要保证同一篇文档内统一。