小樱桃Markdown规范 | XSwitch文档中心

本文是小樱桃使用的Markdown规范，分享给大家，希望对大家有帮助。

什么是Markdown？

Markdown是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。
Markdown语言在2004年由约翰·格鲁伯（John Gruber）创建。
Markdown编写的文档可以导出HTML 、Word、图像、PDF、Epub等多种格式的文档。
Markdown编写的文档后缀为.md、.markdown。
Markdown注重用简洁的标记语法描述文章的章节和段落结构，写文档的人无需要过多关注排版。
与HTML、XML等标记语言类似，Makerdown也是一种标记语言。不同的是，后者是可以给“人”看的，而前者是给浏览器或其它软件看的。

Markdown是格式简单易学又不失强大的功能，目前主流的文档平台都支持Markdown格式。关于Markdown的语法，参见：

在实际使用时，由于软件和平台的不同，Markdown语法也不尽相同，甚至有很多言。小樱桃有时候会使用Markdown同时生成HTML和PDF，因此，为了保持最大兼容性（也为了更好看），制定以下规范，请遵照执行。

标题中

正确：# 综述
错误：#综述

标题上下要空一行

正确：

# 综述

欢迎使用本文档。

错误：

# 综述
欢迎使用本文档。

不需要写章节号

章节号在PDF及Word文档中会自动生成。在我们的Git服务器上，也可以自动生成章节号及目录。

中文文档中用中文标点

正确：注意：中文文档中用中文标点，即使在有跟english、other language混排的情况。
错误：注意:中文文档中有英文标点, 即使在有跟english, other language混排的情况。

中英文混排时中英文间不要加空格

在中、英文间加上适当的距离是排版软件要做的事，而不是要人为的加空格。

正确：使用FreeSWITCH打电话
错误：使用 FreeSWITCH 打电话

注：这一条有争议，有人说加上空格排得好看，但是在有大量中英文混排时有大量的空格输入会比较麻烦，所以我们暂时坚持不要加空格。

中文慎用斜体

中文字体其实没有斜体（除了一个最新的“得意黑”字体），所以慎用。如果表示强调，可以使用黑体或“加上双引号”。

文档末尾至少要有一个空行

如：

1.md：

# 第一章

内容

使用UNIX换行符

新建文档时，一定要确保你的编辑器使用UNIX换行符格式，即使用\n而不是\r\n。

代码格式

行中的代码使用这种格式：如code、12345678等。

`code`

`12345678`

多行代码使用以下格式：

```c
int a;
int b;
```

注意：

代码块上下都要空一行，以方便看出逻辑关系
要使用Fenced Code Blocks，即使用三个反引号包裹代码块，**并添加Fence标记（即语法类型，如c、go）**而不是使用缩进的方式，这样可以保证代码块格式化正确，能高亮显示，以及长行正确换行
Fence代码如果没有相关类型但需要换行时可以使用txt

正确：

```c
int a;
int b;
```

错误（下列代码不容易区分add more code below是代码还是真实文本，且没有Fence）：

see code below:
```
int a;
int b;
```
and more code below:
```
int c;
int d;
```

代码块要有格式说明（Fence），这样便于高亮显示语法，在PDF中也能正确换行，没有格式说明的在PDF中长行不自动换行。如以下代码：

```c
int main(int argc, char **argv) {
    printf("Hello World!\n");
}
```

将显示为：

int main(int argc, char **argv) {
    printf("Hello World!\n");
}

没有格式的代码可以使用txt格式。

流程图尽量用代码方式生成

这样做的好处是图形和文字在同一个文件中。系统目前支持以下方式，在Gitea上可以看图，在VS Code中有相应的预览插件：

graphviz
msc
~~markmap~~ （兼容性不好，不推荐使用）

示例代码如下。可以直接在我们的Git网站上显示图片。生成的PDF中也可以自动生成图片（目前尚不支持markmap，使用Graphviz代替，不大好看）。

无向图：

```graphviz
graph G {
    rankdir = LR;
    a -- b;
}
```

有向图：

```graphviz
digraph G {
    rankdir = LR;
    a -> b;
}
```

有些特殊的图可以用twopi生成，如：

```twopi
digraph G {
    a -> b;
    a -> c;
    a -> d;
    a -> e;
    a -> f;
    a -> g;
}
```

时序图：

```msc
msc {
    alice [label="Alice"],
    bob [label="Bob", textcolor="red"],

    alice -> bob [label = "INVITE(SDP)"];
}
```

思维导图：

```markmap
# 思维导图
## 很好
## 很强大
```

# 思维导图
## 很好
## 很强大

如果使用其它图片，注意保留源文件

如果使用WPS、Word、PPT、Viso、Keynote、OmniGraffle等方式画图，生成.jpg或.png图片后可以在Markdown中使用，并请保留源文件。源文件如果比较小，可以Commit到Git仓库中，如果比较大，则在项目完成后归档放到企业网盘中。

少用表格

表格排版比较麻烦，尽量少用。可以多用列表或思维导图方式代替。如果不得不用，尽量少用字段比较多的表格。以下网站也能帮助生成Markdown表格：

https://tableconvert.com/

VSCode里也有一个表格插件Markdown Table (TakumiI) 对编辑表格有一些帮助。

合理使用元信息

如果最后需要生成PDF，则在文件头部加入元信息（元信息可以在Latex模板中引用），Yaml格式，如：

---
title: 设计文档
author: 杜金房
---

# 第一章

# 第二章

注意，在这种情况下，文档标题写到title元信息里面。所有章节都使用一级标题。

如果标题过长，可以将标题分成两行，但仍保留完成标题，如：

---
title: 本文档有一个很长很长的标题以至于会换行
title1: 本文档有一个很长很长的标题
title2: 以至于会换行
author: 杜金房
---

# 第一章

# 第二章

列表

为保持紧凑，列表项目间不需要有空行。列表中的标点有以下三种方式：

* 短句不加标点
* 这样，其实也行

* 比较长的句子可以加句号。
* 但要注意：或者都加，或都都不加。
* 不要有的加有的不加。

* 有时候，可以用分号；
* 并在最后一条上用句号；
* 但不推荐使用这种方式，因为如果后面你想在最后再加上一条，有时忘了将上一条的句号改成分号。

尽量使用上述无序列表，少用有序列表。

章节和标题

以下是关于章节和标题的建议。

单篇文章

单篇文章使用一级标题：

# 文章标题

## 二级标题

在一些文档场景，为了SEO需要，可能使用元信息默认生成一级标题（HTML中的<h1/>），这样的文件要从二级开始。如：

---
title: 文章标题
description: 摘要信息，用于SEO文档描述。
---

本文档是...文档，请仔细阅读。

## 二级标题

内容...

长文档

如果文档太长，则放到一个子目录中分成多篇文档（相当于章节），如：

xswitch-user
  |--- chapter1.md
  |--- chapter2.md
  |--- chapter3.md
  |--- big-chapter4
  |      |--- section1.md
  |      |--- section2.md
  |--- chapter5.md

标题不要悬空

标题一般不要悬空，即标题下要有东西，不要一级标题下接着二级标题，如：

正确：

# 概述

本文档是...

## 设计理念

下面我们来看一下设计理念。

### 一切为了用户

内容...

### 客户至上

内容...

不大正确：

# 概述

## 设计理念

### 一切为了用户

内容...

### 客户至上

内容...

更不越级，如一级标题下面直接三级标题 。

标题级别

建议最多使用四级标题（特殊情况下也可以使用五级标题），如果章节比较深，可以使用自然段落，如：

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

1) 第一种情况，小节号使用英文括号，后面加一个空格

内容...

2) 第二种情况

内容...，还有以下几种情况：

a) ...
b) ...

在pandoc中，默认4级及以下的标题都不生成目录，如果要生成目录，可以使用--toc-depth=4实现。

article类型

默认生成的PDF都是按章节的。有时候，内容比较少，无法分章节，只有一章看起来会比较奇怪，这时候，可以使用article类型，在pandoc命令行上使用--variable documentclass="report"以及--variable article="true"两个参数，并去掉--toc。

链接和跳转

如果在文档中加入链接，要看具体情况。

基本链接规则

基本的链接规则如下：

内部链接可以在标题上添加自定义锚点，如## 标题二 {#section2}，通过这种方式，可以避免链接中出现带百分号的链接地址，更易读
在同一个文档内，尽量使用短链接，如链接到链接和跳转可以使用：[链接到链接和跳转](#link)实现
同一个网站上的文档，不要使用域名
不同网站上的文档，使用带域名的绝对路径
当需要兼容生成PDF时，下一节的相关规则优先考虑

PDF引用规则

如果Markdown最终要生成PDF，可以使用参见第\ref{section2}节这样的代码直接引用文件内的锚点。如果文件不能产生锚点，也可以使用\label{my-label}添加标签作为引用锚点。

注意，这种方法只有在生成PDF时才有用，如果生成Word时，会生成“参见第节”这样的内容，如果生成HTML时，\ref{}会原样输出。如果需要兼容，可以使用参见\ref{basic-link-rule} [基本链接规则]{#basic-link-rule}，这样的语法，如：参见\ref{basic-link-rule} [基本链接规则]{#basic-link-rule}。

其它

文档内容至少要在小樱桃Gitea上正常显示。
并能配合相应模板生成正确的PDF。
在Gitea上，可以点击本文档右上方的编辑按钮查看文档源文件。
其它可参见中文技术文档写作规范，该规范仅供参考，但我们并不是完全按这个规则来。

限制

目前在我们的Git页面上不支持预览时看图。
目前Markmap的图尚不支持在PDF中生成，少用。

文档生成

可以使用Pandoc和Latex生成Word、HTML和PDF文档。为了方便使用，我们制作了Latex Docker镜像。

ccr.ccs.tencentyun.com/free/pandoc:3.0.1：最新版的Docker镜像，Pandoc 3.0.1。
ccr.ccs.tencentyun.com/free/pandoc:tiny-3.0.1：最新版的Docker镜像，Pandoc 3.0.1。
ccr.ccs.tencentyun.com/free/pandoc：Pandoc 2.19.2，基于Debian 12，支持ARM64和AMD64，包含mscgen（增加了高分辨率支持）。
ccr.ccs.tencentyun.com/free/pandoc:tiny：Pandoc 2.19.2，比上一个稍微小一点，基于Debian 12以及TinyTeX，支持ARM64和AMD64，包含mscgen（增加了高分辨率支持）。
ccr.ccs.tencentyun.com/free/pandoc:multiarch：旧新版的Docker镜像，基于Ubuntu Jammy，支持ARM64和AMD64，包含mscgen（不支持高分辨率支持）。
ccr.ccs.tencentyun.com/free/texlive_pandoc:m1：旧版Apple M1版Docker镜像，基于Ubuntu Jammy，包含mscgen（不支持高分辨率支持）。
ccr.ccs.tencentyun.com/free/texlive_pandoc：更旧版Docker镜象。

更旧版Docker镜象不包含mscgen，推荐使用第一个镜象。但第一个镜象不支持zhspacing，所以如果旧的文档编译出错，可以把template里的zhspacing相关的行注释掉。

使用方法：

docker run --rm -it -v ${PWD}/..:/team ccr.ccs.tencentyun.com/free/pandoc bash
cd src # 根据情况看是否需要
make

关于文档生成和排版更详细的说明参见《技术图书排版》。

文档共享

把文档上传到微信网盘，在macOS上的路径是：~/Library/Containers/com.tencent.WeWorkMac/Data/WeDrive/小樱桃科技/

可以直接通过网盘上传，或通过Makefile实现，如：

DEST := ~/Library/Containers/com.tencent.WeWorkMac/Data/WeDrive/小樱桃科技/项目与方案/解决方案/


install:
	cp ../pdf/xswitch-*.pdf $(DEST)

注意：如果目标文件在网盘上已存在，则必须下载后才能覆盖，或者，可以在make install前将网盘上的目标文件删除。