跳转至

文档排版规则

本章介绍香山文档中允许使用的 Markdown 标记语法，以及标记语法以外的一些排版规则。

Note

本章仅适用于使用新版文档框架的用户手册和设计文档。

由于新版文档框架同时使用 Mkdocs 和 Pandoc 两套工具链来分别生成在线网站和 PDF 版式文件，我们在撰写文档时需要同时满足两方的要求和约定。

章节标题

章节标题以 # 号开始，# 号的数量表示标题的级别，如：

# 这是一级标题
## 这是二级标题
### 这是三级标题
#### 这是四级标题

请注意：

  • # 号与标题实际内容间须有一个空格；
  • 标题行与前后段落间须有至少一个空行；
  • 请注意控制章节标题的层次数，具体可参考 结构 一章。

章节标题还可以使用 abbr_list 语法来创建锚点，如下所示，具体请参见交叉引用一节。

# 这是一级标题 {#sec:this-is-heading-level-1}
## 这是二级标题 {#sec:this-is-heading-level-2}
### 这是三级标题 {#sec:this-is-heading-level-3}
#### 这是四级标题 {#sec:this-is-heading-level-4}

段落

多段文本间使用空行分隔，如：

这是第一段，用来测试段落效果。内容并不重要，只是为了填充文字。

这是第二段，主要作用是与第一段区分开来。这里的文字依旧是随机编排，没有实际意义。

请注意：

  • 推荐每个段落在 Markdown 源码中保持为一行，按固定宽度自动折行应该交给编辑器来自动完成；
  • 通常情况下，不推荐在文档中添加强制换行符，包括行末的两个连续空格或 HTML 标签 <br>。
  • 如果需要在内容上分隔，请另起一段；
  • 如果需要严格的行内对齐，请考虑使用代码块实现。

空格

撰写文档时，应当遵守以下空格使用的规则：

  • 中文与英文之间需要增加空格，如：香山文档使用 Markdown 标记语言编写
  • 中文与数字之间需要增加空格，如：香山的开发始于 2019 年
  • 数字与单位之间需要增加空格，如：南湖的设计目标是在 14 nm 工艺节点下频率达到 2 GHz
    • 例外，度数、百分比与数字之间不加空格，如：180° 和 15% 是两个例子
  • 强调文字、行内代码、超链接的前后需要增加空格，如：请注意 **这里** 是强调
  • 全角标点与其他字符间不加空格，如：香山使用的硬件描述语言是 Chisel。

由于技术限制，在一定情况下（如文档中的变量替换），可以加入额外的空格而忽略上述规则。

中英文间加入的空格是为了美观和易读，本应由排版引擎自动完成。但考虑到网页浏览器渲染的实际情况，只能退而求其次手动添加空格。

强调

使用以下方法为文本添加强调效果：

  • 斜体：在文本前后分别加上 *
  • 粗体：在文本前后分别加上 **
  • 粗斜体：在文本前后分别加上 ***
尝试将 **文本** 加粗。Try to make **text** bold.

Try to make *text* italic.

Try to make ***text*** bold and italic.

请注意：

  • 任何情况下都不应将中文设为斜体；
  • 强调文字的前后需要增加空格；
  • 不推荐使用下划线（_）的强调语法。

代码

代码分为行内代码与代码块两种，使用等宽字体显示或排印。下列内容须使用代码样式：

  • 代码、伪代码、命令、脚本等；
  • 变量名、信号名、寄存器名、位域名、模块名、函数名、类名等各类标识符；
  • 需要等宽字体来是实现严格对齐的内容。

请注意：

  • 英文单词、专有名词、缩写一般不需要使用代码样式；
  • 注意区分代码与公式的应用场景：描述程序实现用代码，描述数学关系用公式；
  • 尽量避免在代码中使用中文字符。

行内代码

要将文本表示为行内代码，可在文本前后分别加上反引号 `。行内代码的前后（反引号的外侧）需要增加空格，但与全角标点之间不加空格。

我们需要使用 `valid` 和 `ready` 信号来控制 `DecoupledIO`。

代码块

要将一段文本表示为代码块，可在其开始和结尾处分别增加一行 3 个反引号 ```。其中，首行的 ``` 后可以添加代码的语言。代码块也是一种“段落”，请务必确保代码块前后都有空行。

下面是一个 Chisel 代码块。

```scala
val io = IO(new Bundle() {
  val foo = Bool()
  val bar = Bool()
})
```

上面是一个 Chisel 代码块。

基于兼容性考虑，不应使用缩进来标记代码块。

Note

你可能好奇这里是如何在代码块里嵌套代码块的语法，这是通过比标准的语法使用更多的 ` 来实现的。要在代码块中使用 n 个连续的 `，则需要使用有 n+1 个 ` 来包裹。例如，对于行内代码，要显示 `，可以使用 `` ` ``。虽然香山的文档中通常用不到，但在这里介绍一下以防你感兴趣。

公式

公式分为行内公式和公式块（行间公式）两种，使用 LaTeX 语法编写，使用数学字体显示或排印。

请注意：

  • 英文单词、专有名词、缩写不需要使用公式样式；
  • 注意区分代码与公式的应用场景：描述程序实现用代码，描述数学关系用公式；
  • 撰写数学公式时须遵循数学公式的一般规则，不能混用编程语言中的语法（如 r, p = PearsonCorr(d, w)）；
  • 对于简单公式，可以直接使用 Unicode 数学符号，如 y = x² + b；
  • 尽量避免在标题中使用公式；
  • 尽量避免在公式中使用中文字符，不应在公式中使用全角符号。

行内公式

要使用行内公式，须在 LaTeX 公式的前后分别加上单个美元符号 $。行内公式的前后（一对美元符号 $ 的外侧）须增加空格，但与全角标点之间不加空格。LaTeX 代码与 $ 之间通常不加空格。

将 $x = y + 2$ 带入方程 $3x + 2y = 5$。

考虑到兼容性问题，不推荐使用 \( 和 \) 来包裹行内公式。

公式块（行间公式）

要使用行间公式，须在 LaTeX 公式段落的前后分别加上连续两个 $$，或以 \[ 开头、以 \] 结尾。$$、\[、\] 通常单独占一行。公式块前后通常应各保留一个空行。

下面是一个公式块。

$$
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$

上面是一个公式块。

列表

列表用于组织多个条目，分为有序列表和无序列表。

有序列表

要创建有序列表，可在每个列表项前添加数字并紧跟一个英文句点，英文句点与列表项之间须有至少一个空格。列表应以数字 1 开始，数字应尽量按顺序排列。缩进一个或多个列表项可创建嵌套列表。列表也是一种“段落”，请务必确保列表前后都有空行。

下面是一个嵌套的有序列表。

1. 项目一
2. 项目二
    1. 子项目 1
    2. 子项目 2
3. 项目三
    * 子项目 a
    * 子项目 b

无序列表

要创建无序列表，可在每个列表项前添加 *、-、+ 符号，符号与列表项之间须有至少一个空格，单个列表必须使用一样的符号。缩进一个或多个列表项可创建嵌套列表。列表也是一种“段落”，请务必确保列表前后都有空行。

下面是一个嵌套的无序列表。

* 这是第一个项目
* 这是第二个项目
    * 这是第一个子项目
    * 这是第二个子项目
* 这是第三个项目
    * 这是第一个子项目
    * 这是第二个子项目

引用

要创建引用，请在段落的每一行前增加一个 > 符号。引用中可包含多个段落，亦可嵌套。

> 这是一段引用。

信息块

Warning

很不幸，新版文档框架暂时还不能支持信息块（Admonitions）语法，这主要是因为 Mkdocs-Material 和 Pandoc 使用的语法不太一致。如果你对解决这个问题感兴趣，可以帮助我们写一个 Pandoc 的 filter 来将 Mkdocs-Material 的语法转化为 Pandoc 支持的语法。

超链接

要创建一个超链接，可将链接文本放在中括号内，将链接地址放在后面的圆括号中。链接前后须增加空格，但与全角标点之间不加空格。

这是一个指向香山网站的 [链接](https://xiangshan.cc)。

图片

要插入图片，请以感叹号 ! 开始，将图片标题放在中括号内，将图片链接放在后面的圆括号中。图片之后还可以使用 abbr_list 语法增加锚点，具体参见“交叉引用”一节。

![图片标题](figs/figure1.md){#fig:figure1}

图片应当作为单独的“段落”存在，前后均须添加空行。每张图片都应当有图片标题。

Note

需要注意的是，我们实际上是将图片标题放在了代替文本（alt）的位置，而留空了标题（title），这主要是因为 Pandoc 的偏好。总之目前能用。

推荐使用 svg 格式的图片，构建时会自动将它们转化为 pdf 格式。svg 格式图片在导出时坑可能存在一些限制，请根据构建结果及时调整。

图片链接是图片文件相对于当前 Markdown 文件的相对路径。推荐将图片放入 markdown 文件同级目录的 figures 目录。

├── Section1
│   ├── index.md
│   ├── figures
│   │   └── figure.md
│   └── the-file-using-figure.md

表格

新版文档框架可使用普通 Table 和 Grid Table 两种类型的表格。

普通 Table

普通 Table（Pipe Table）源自 PHP Markdown Extra，是目前 Mardown 方言中使用最广泛的表格语法。

Table: Sample Table

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

其中：

  • 单元格中不能包含段落、列表等块元素，也不能跨越多行，亦不允许使用 <br> 在表格内换行；
  • 表格线符号 | 用于指示列的边界，但表格线符号 | 并不强制要求对齐；
  • 在 PDF 流程中，表格各列的宽度是根据第二行（即表头与表身的分隔线）的破折号数量确定的；
  • 第二行（表头与表身的分隔线）中的冒号 : 用于表示左对齐、右对齐、居中或默认。

表格前以 Table: 开头的段落为表格标题，每个表格都应当有表格标题。表格标题后可以使用 abbr_list 语法增加锚点，具体参见“交叉引用”一节。

Grid Table

Grid Table 源于 reStructuredText docutils，是一种支持更多复杂表格需求的表格格式，具体语法请参考 Pandoc 文档。

Table: Sample grid table

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

其中：

  • Grid Table 可以在表格内换行，也可以在表格内插入列表等其他块元素。
  • Grid Table 可以合并单元格，只需要去掉对应的框线的 | 、- 等符号即可。
  • Grid Table 要求 表格框线必须在准确位置。
    • 一个中文字符对应两个英文字符，可利用终端等具有强制对齐功能的工具协助检查框线对齐情况。
    • 如果可能，请尽量不要在 Grid Table 中使用中文。

表格前以 Table: 开头的段落为表格标题，每个表格都应当有表格标题。表格标题后可以使用 abbr_list 语法增加锚点，具体参见“交叉引用”一节。

Note

Grid Table 的处理基础设施较为脆弱，兼容性可能偏差，如果不是必须，请尽量避免使用 Grid Table。

交叉引用

新版文档框架引入了 pandoc-crossref 风格的交叉引用系统，分为标记锚点和添加引用两个部分。

标记锚点

使用形如 {#<type>:<label>} 的 attr_list语法为章节、图片、表格添加锚点，其中：

  • <label> 部分应为 sec（章节）、fig（图片）、tbl（表格）之一；
  • <label> 部分为锚点标签，推荐使用连字符 - 来链接单词，应当确保其在整个文档中唯一。

请注意，attr_list 串与图片语法之间没有空格，但与标题、表格标题之间有一个空格。

<!-- 标记一个章节 -->
# 特权指令 {#sec:priv-inst}

<!-- 标记一个图片 -->
![架构图](figures/arch.svg){#fig:arch}

<!-- 标记一个表格 -->
Table: 某某部分术语表 {#tbl:xxx-terms}

| col1 | col2 |
|------|------|
|  12  |  12  |

添加引用

使用形如 [@<type>:<label>] 的 crossref 语法来添加引用，<type>、<label> 应与锚点完全一致。可以同时引用多个，使用 ; 将多个锚点标识符分隔开即可。引用语法前后需要增加空格，但与全角标点之间不加空格。

参见 [@sec:priv-inst] [特权指令](priv-inst.md)。

如 [@fig:arch] 所示。

参见 [@tbl:xxx-terms]。

也可以同时引用多个，参见 [@fig:arch; @tbl:xxx-terms]

引用章节时，需要同时写两种形式的引用：

  • [@sec:label] 的 crossref 形式，整个文档（所有 md 文件）中 label 应当是唯一的；
    • PDF 中用于自动导出章节编号和链接，形如 §1.1
    • 网页中会自动移除
  • [标题](path/to/file.md#sec:label) 的链接形式；
    • 用于在网页中提示章节标题，形如 特权指令
    • PDF 中会自动移除

使用 crossref 语法引用图片、表格时：

  • PDF 中会被渲染为 图 1.1、表 2.1
  • 网页中会被渲染为 此图、此表

Note

目前，新版文档框架在 Mkdocs 上对交叉引用的支持仍然只是个半成品：引用章节时须大费周章，图表在标记和引用时均无编号……欢迎提 PR 来改进我们为 python-markdown 制作的 crossref 插件。

其他注意事项

不要使用 HTML 或 LaTeX 语法

请不要在 Markdown 混入 HTML 或 LaTeX 语法。尽管使用某一种工具链时它们能够正常工作，但换用另一种工具链时就可能不会被正确渲染。一些常见的不能使用的 HTML 和 LaTeX 语法有：

  • <br> HTML 换行
  • \newpage LaTeX 分页

事实上，我们确实应该提供一种方法来强制要求在特定位置（如章节开始或结尾处）分页。如果你有相关的想法，欢迎提 PR 来协助解决此议题。

参考文献

本章节内容参考了一下文献：