小樱桃 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打电话

如果英文靠着标题符号，当然不要加：

正确：我喜欢 FreeSWITCH。
错误：我喜欢FreeSWITCH 。

手工插入空格很麻烦，建议使用 VSCode 的Prettier - Code Formatter插件提供的格式化功能（在 macOS 上的 Opt + Shift + F）。在实际使用时，每次修改文档之前，尽量先检查文档是否符合自动格式化的规范，如果不符合，建议单独将格式化的修改提交，以方便看 diff，减少冲突。

有些情况下，Prettier 会搞乱格式，可以使用  禁掉下一个代码段的自动格式化功能，或使用如下方法禁掉一个片断。参见：https://github.com/prettier/prettier-vscode/issues/3332 。

<!-- prettier-ignore-start -->
这里的内容不会自动格式化 ...
<!-- prettier-ignore-end -->

注：苹果和微软的网站上中英文混排也都加入了空格。

中文慎用斜体

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

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

如：

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)"];
    bob -> alice [label = "200 OK(SDP)"];
}
```

思维导图：

```markmap
# 思维导图 {#markmap}
## 很好
## 很强大 {#markmap-strong}
```

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

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

如果使用 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:tiny-3.2：最新版的 Docker 镜像，Pandoc 3.2，增加了一些 Sarasa 字体。
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前将网盘上的目标文件删除。