188 lines
5.8 KiB
Markdown
188 lines
5.8 KiB
Markdown
|
<div align=center><font size=5>众望通科技 研发中心</font></div>
|
|||
|
|
<div align=center><font size=6>Markdown文档排版规范</font></div>
|
|||
|
|
|
|||
|
|
> <div><font>拟稿：周志尧</font></div>
|
|||
|
|
> <div><font>版本号： 1.0.0 </font></div>
|
|||
|
|
> <div><font>发布时间：2020.10.06 </font></div>
|
|||
|
|
|
|||
|
|
[TOC]
|
|||
|
|
|
|||
|
|
## 1 语法规范
|
|||
|
|
|
|||
|
|
推荐使用 [GitHub GFM](https://link.zhihu.com/?target=https%3A//github.github.com/gfm/) 规范
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 2 排版规范
|
|||
|
|
|
|||
|
|
### 2.1 标题层级
|
|||
|
|
|
|||
|
|
- 文章的顶层标题使用 **二级标题**
|
|||
|
|
- 每个小节的标题使用 **三级标题**
|
|||
|
|
- 小节中需要进一步分层组织时，使用 **四级标题**
|
|||
|
|
- 尽量少用 **五级标题** 和 **六级标题**，考虑用有序列表和无序列表代替
|
|||
|
|
- 完全不用 **一级标题**
|
|||
|
|
- 标题的 **序号数字** 和 **标题文字** 之间空一格
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.2 空行
|
|||
|
|
|
|||
|
|
- 不要有多余的空行，不要连续空两行及以上。
|
|||
|
|
|
|||
|
|
- 文件末尾空一行，大多数格式检查工具都会检查文件末尾的空行。
|
|||
|
|
|
|||
|
|
- 正文段落之间用一个空行来分隔，可以显得段落分明、结构不拥挤，如：
|
|||
|
|
|
|||
|
|
> Markdown 是一种标记语言。在写作时，你的所有文字都是没有样式的纯文本，在其中插入若干 Markdown 标记后，被标记的文字便有了样式。
|
|||
|
|
>
|
|||
|
|
> 比如，在你所写的文字中，希望某一行的最终排版呈现一级标题的样式，那就给这行文字加个一级标题的标记；某个地方有两个字需要加粗，那就给这两个字加个粗体标记。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.3 空格
|
|||
|
|
|
|||
|
|
Markdown 中 **半角空格** 的使用很重要，一些情况下能调节文字间距使得排版更加美观：
|
|||
|
|
|
|||
|
|
* 中英文之间需要增加空格
|
|||
|
|
|
|||
|
|
> 在 LeanCloud 上，数据存储是围绕 `AVObject` 进行的。
|
|||
|
|
|
|||
|
|
* 中文与阿拉伯数字之间需要增加空格
|
|||
|
|
|
|||
|
|
> 今天出去买菜花了 5000 元。
|
|||
|
|
|
|||
|
|
* 数字与单位之间需要增加空格（例外：度 / 百分比与数字之间不需要增加空格）
|
|||
|
|
|
|||
|
|
> 我家的光纤入屋宽带有 10 Gbps，SSD 一共有 20 TB。
|
|||
|
|
>
|
|||
|
|
> 新 MacBook Pro 有 15% 的 CPU 性能提升。
|
|||
|
|
|
|||
|
|
* 链接之间增加空格
|
|||
|
|
|
|||
|
|
> 访问我们网站的最新动态，请 [点击这里](http://www.chinaweal.com.cn:8090/pms/#/knowledgeBase/index) 进行订阅！
|
|||
|
|
|
|||
|
|
* 加粗、斜体、高亮文本前后加空格
|
|||
|
|
|
|||
|
|
> 修复了一个 **内存泄露** 问题，该问题由 *someone* 在 `版本 v0.1.1` 中引入。
|
|||
|
|
|
|||
|
|
* 全角标点与其他字符之间不加空格
|
|||
|
|
|
|||
|
|
> 刚刚买了一部 iPhone，好开心！
|
|||
|
|
|
|||
|
|
- 行内代码的两端各添加一个空格。若行内代码紧邻标点符号，则其与标点之间 **不加** 空格
|
|||
|
|
|
|||
|
|
> 打开 Linux 虚拟终端，输入 `echo 'Hello World'`。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.4 全角和半角
|
|||
|
|
|
|||
|
|
查看百科词条 [全角](https://baike.baidu.com/item/%E5%85%A8%E8%A7%92/9323113) 和 [半形](https://baike.baidu.com/item/%E5%8D%8A%E8%A7%92)。
|
|||
|
|
|
|||
|
|
* 使用全角中文标点
|
|||
|
|
|
|||
|
|
> 嗨！你知道嘛？今天前台的小妹跟我说「喵」了哎！
|
|||
|
|
|
|||
|
|
* 数字使用半角字符
|
|||
|
|
|
|||
|
|
> 这个蛋糕只卖 1000 元。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.5 粗体、斜体
|
|||
|
|
|
|||
|
|
* 粗体
|
|||
|
|
|
|||
|
|
需要强调某处内容时使用 **粗体**，如：
|
|||
|
|
|
|||
|
|
> 中文全角标点符号占 **一个** 汉字宽度，英文半角标点占 **半个** 汉字宽度（亦即一个字母宽度）。
|
|||
|
|
|
|||
|
|
* 斜体
|
|||
|
|
|
|||
|
|
在中文排版中不使用 **斜体**。
|
|||
|
|
|
|||
|
|
在英文排版中可用斜体表达强调，或表示书名、题目。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.6 代码
|
|||
|
|
* 行内代码
|
|||
|
|
|
|||
|
|
某一行文字中嵌入简短代码时使用 **行内代码**，如：
|
|||
|
|
|
|||
|
|
> 打开 Linux 虚拟终端，输入 `echo 'Hello World'` 。恭喜，你已经入门 Shell 了 ：）
|
|||
|
|
|
|||
|
|
* 代码块
|
|||
|
|
|
|||
|
|
展示多行代码时使用 **代码块**，也可用于 XML、JSON、配置项等。尽量在使用代码块时给出语言标识，Markdown 工具会针对该语言高亮显示其中的语言元素。如：
|
|||
|
|
|
|||
|
|
> \```java
|
|||
|
|
> public class Main {
|
|||
|
|
> public static void main(String[] args) {
|
|||
|
|
> System.out.println("Hello World");
|
|||
|
|
> }
|
|||
|
|
> \```
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.7 图片
|
|||
|
|
|
|||
|
|
Markdown 中使用
|
|||
|
|
|
|||
|
|
> )
|
|||
|
|
|
|||
|
|
来插入图片，这里的「图片名称」可以任取，但是推荐使用对图片主题具有描述性的文字。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.8 转义符号
|
|||
|
|
|
|||
|
|
如果不想让 Markdown 标记生效，可以在标记的每个符号前加上反斜杠 \，这样这些符号将按原样显示，不再具有 Markdown 中的特殊意义。
|
|||
|
|
|
|||
|
|
如：
|
|||
|
|
|
|||
|
|
> 不想让引用块标记生效，可以使用 **\>**，将显示为 **>**
|
|||
|
|
> 不想让二级标题标记生效，可以使用 **\#\#**，将显示为 **##**
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.9 缩进
|
|||
|
|
- 文章中每个段落的开头 **不要** 缩进。
|
|||
|
|
- 列表中嵌套列表时，内层列表使用 4 个空格进行缩进。
|
|||
|
|
- 缩进时使用空格符，不用 Tab 符。
|
|||
|
|
- 在使用有序列表时，建议同级之间空一行，在上下级不用空行。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 2.10 中文标点符号规范
|
|||
|
|
|
|||
|
|
* 标点通用规则
|
|||
|
|
|
|||
|
|
中文排版时应全文使用中文全角标点，无论内容中是否包含英文词语。
|
|||
|
|
|
|||
|
|
* 省略号
|
|||
|
|
|
|||
|
|
在中文输入法状态下，可使用「Shift + 6」输入省略号。注意是 6 个点，而非 3 个点，如：
|
|||
|
|
|
|||
|
|
> 中文里常用的标点有逗号、句号、顿号、冒号……
|
|||
|
|
|
|||
|
|
* 破折号
|
|||
|
|
|
|||
|
|
在中文输入法状态下，可使用「Shift + -」输入破折号。注意该符号应占两个汉字宽度，如：
|
|||
|
|
|
|||
|
|
> 破折号，标示语段中某些成分的注释、补充说明或语音、意义的变化。 ——《标点符号用法》
|
|||
|
|
|
|||
|
|
* 波浪线
|
|||
|
|
|
|||
|
|
在中文输入法状态下，可使用「Shift + `（ESC 键下方）」输入波浪线。可用波浪线表示数值的区间，如：
|
|||
|
|
|
|||
|
|
> 只要 10～20 分钟你便能掌握这篇文章的要领。
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 3 工具推荐
|
|||
|
|
|
|||
|
|
编辑器：[Typora](https://typora.io/)，[详细教程](https://sspai.com/post/54912)
|
|||
|
|
|
|||
|
|
Web开发使用插件推荐：[mavonEditor](https://github.com/hinesboy/mavonEditor)
|