文档编写规范书

October 2, 2024 · 9 min read

Twiyin0

音铃 || 沃玛频道超管, 是个吉祥物

tip

为了规范文档编写，提高文档质量，特制定此文档编写规范书。
该部分包含对标题命名、特殊符号使用等规范

此网站所有目录下的文档都使用markdown编写，此规范使用于本站所有markdown(.md或.mdx文件)

此网站所有目录下的文档都使用markdown编写，此规范使用于所有markdown(.md或.mdx文件)

一般规范

跳转的链接一定要确保是正确的，可以使用vscode的ctrl+click跳转，看是否跳转到正确位置
一般标题不超过四级，特殊情况下可使用五级标题（如文档内需要跳转、样式无法满足要求等）
正文中含有特殊符号可以使用\转义,如果是组合可以在第一个符号前转义\<aa>,\[abc](),\&
换行使用双空格+回车或者 , 。当然你可以使用*,-等列表的形式换行
markdown语法遵循Markdown 官方教程
markdown语法速查表可查看Markdown 语法速查表

标题规范

标题尽量不要超过5级

标题非必要情况下不要加粗，如果有特殊需求（如警告、危险等强调的地方）可以使用加粗或者更改颜色注: 更换颜色的代码为
```
文本
```
或者你也可以使用以下代码，但是这会导致文本字体不同于正文，不太推荐
```
$\color{#ffae1a}{文本}$
```
举例: 危险 || 危险
```
危险 || 危险
```
或
```
$\color{red}{危险}$ || $\color{#00BFFF}{危险}$ # {危险}的{}可以省略，看个人习惯
```

如果标题中含有标号（如一、二、三、四等）不方便跳转的可以使用以下代码
#（几级都行）{#custom-id}

### 三、标题三 {#title-3}
跳转时用
[跳转到标题三](#title-3)

不过我建议遵循以下几点

使用格式为(#一级标题-二级标题-三级标题)，例如跳转到3.1.2可以这样操作

# 三、第三个一级标题 {#3}
## 3.1 第三个一级标题的第二个二级标题 {#3-2}
### 3.1.2 第三个一级标题的第二个二级标题的第三个三级标题 {#3-2-3}

跳转时用
[三、第三个一级标题](#3)
[第三个一级标题的第二个二级标题](#3-2)
[第三个一级标题的第二个二级标题的第三个三级标题](#3-2-3)

每个 Markdown 文档会在右上角显示一个目录栏。目录默认只显示 h2 和 h3 标题。如果需要显示多级标题，可以在md文件头部---内使用以下代码

---
# 显示 h2 到 h5 标题
toc_min_heading_level: 2
toc_max_heading_level: 5
---

正文规范

正文需要保证格式不会出错，推荐使用vscode插件Markdown Preview Enhanced
安装后ctrl+shift+v可以预览markdown文件，可以使用这个插件检查自己的正文内容是否有误
不同重点可以用不同颜色区分，同一个页面内不要出现太多重点，避免页面混乱

文件命名与图片存储位置规范

原有的文件与文件名不可变动，避免链接损坏从而导致项目无法编译
文档文件名不得使用中文，非必要不使用拼音，可以机翻（
本地图片存储位置可以在md文件所在位置新建/img文件夹，如果md所在位置有多份md文件则在img文件夹内再创建对应md文件的子文件夹，将相关为突破或媒体放入其中。图片尽量不要超过10M。目录结构如下这样可以避免引用图片时链接出错
```
/(root)
/img
./awa
../img.jpg
./bbb
../img-b.png
awa.md
bbb.md
```

思维导图的使用

本文档已支持mermaid语法，可以绘制思维导图，使用方法如下

\```mermaid # 省略掉这个\,这个只是为了防止语法出错加的转义符
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
\```

示例效果

更多语法可参考mermaid.js

选项卡使用规范

选项卡是个好东西，能把一些相似的内容放在一起节省页面空间
selectCrad
使用方法:

在md文件前面引入以下代码, 一定要引入，不然会报错

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

在需要使用选项卡的地方使用以下代码

    <Tabs>
    <TabItem value="apple" label="Apple" default>
        This is an apple 🍎
    </TabItem>
    <TabItem value="orange" label="Orange">
        This is an orange 🍊
    </TabItem>
    <TabItem value="banana" label="Banana">
        This is a banana 🍌
    </TabItem>
    </Tabs>

效果如下

Apple
Orange
Banana

This is an apple 🍎

告示语法规范

除了基本markdown语法外，还可以用以下语法来制作告示
以下由上至下重要程度依次增加

:::note[备注]
这是一个备注
:::

:::tip[提示]
这是一个提示
:::

:::info[信息]
这是一个信息
:::

:::warning[警告]
这是一个警告
:::

:::danger[危险]
这是一个危险
:::

效果如下

备注

这是一个备注

提示

这是一个提示

信息

这是一个信息

警告

这是一个警告

危险

这是一个危险

版本号命名规范

版本号统一写在/docs/notice/commit-ji-lu.md文件内，别的地方就不要写了，影响观感
版本号格式为 w.x.y.z
- w: 文档模板版本号(一般由音铃)更改: 文档模板项目更改后+1
- x: 文档主题版本号(一般由音铃)更改: 主页或者主题更换后+1
- y: 文档增减版本号: 每增减一个md文档则+1
- z: 文档修改版本号: 没有新增md文档但是修改了md文件则+1
版本号不是必须的，建议写上，方便以后查阅
版本号后可附加by.{username}与时间
如果上一个修改者没有更改版本号，你可以选择跳过，也可以选择从上面的版本号上新增

一般规范​

标题规范​

正文规范​

文件命名与图片存储位置规范​

思维导图的使用​

选项卡使用规范​

告示语法规范​

版本号命名规范​