XSwitch通信百科

小樱桃 Markdown 规范

本文是小樱桃使用的 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 会搞乱格式,可以使用 <!-- prettier-ignore --> 禁掉下一个代码段的自动格式化功能,或使用如下方法禁掉一个片断。参见:https://github.com/prettier/prettier-vscode/issues/3332

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

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

中文慎用斜体

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

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

如:

1.md

# 第一章

内容

使用 UNIX 换行符

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

代码格式

行中的代码使用这种格式:如code12345678等,这样写:

`code` 或 `12345678` 等

多行代码使用以下格式:

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

注意

  • 代码块上下都要空一行,以方便看出逻辑关系
  • 要使用 Fenced Code Blocks,即使用三个反引号包裹代码块,并添加 Fence 标记(即语法类型,如cgo 而不是使用缩进的方式,这样可以保证代码块格式化正确,能显示正确的代码语法,以及长行正确换行
  • 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}
```
# 思维导图
## 很好
## 很强大

相关链接:

freeswitch.org.cn、xswitch.cn、rts.cn 上面也支持这种渲染。

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

如果使用 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前将网盘上的目标文件删除。

小樱桃技术人员必读