Markdown 文档排版规范

摘要： Markdown 文档在各平台渲染效果差异大，记录 8 条排版规范以避免样式问题。

---

1. 全/半角符号

1. 书写时一律采用英文符号

   hello, my friends, welcome 你好, 我的胖友, 欢迎你的到来

2. 使用符号后一定要空格

   Hello, world! beautiful 世界, 你好

---

2. 图片的使用

Markdown 中图片引用有以下几种方式：

方式	示例	说明
直接引用		最常用
变量引用	[avatar]: 图片地址	推荐，结构清晰
HTML 标签	<img />	仅用于定义图片大小

推荐第二种，原因：结构清晰、一目了然、定位准确、文档美观。将图片变量全部放在文档底部。

注意：不要使用 img 标签去设置图片大小。

---

3. 外链的使用

方式	示例	推荐
直接链接	<https://baidu.com>
a 标签	<a href='...' target='_blank'>baidu</a>
行内引用	[百度](https://baidu.com)
变量引用	[baidu.com]	✅ 推荐

---

4. 列表的使用

Markdown 分为有序和无序两种：

• 有序列表：以数字开头，紧接着一个 . 号，之后空格
• 无序列表：以 +、-、* 开头紧接空格

注意：第一级别尽量使用有序列表。

---

5. 表格的使用

字段	说明	默认值
name	用户名	none: string

注意：

• 使用表格做到职责分明，有子属性的字段尽可能拆分放到下一个表格
• 表格样式居中，不强求，居中对齐更美观

---

6. 标题拆分

不好的结构：

# 标题
这是对这个标题的一段说明，只是一段普通的文本，但是下面我需要引入图片了
<img src='https://baidu.com' alt='preview' />
这里的文本我接着写对这一个标题的或者是图片的描述

改进后的结构：

## 标题

另起一行写第一段描述：这里是描述
换行

现在要插入图片了

插入图片的意图，简单说明，十个字以内，手机屏幕最小展示 10em 左右
![preview](https://img.png)

再次换行
这里写第二段描述

注意：使用标题后一定要换行。

---

7. 提示性语句加粗

提示性语句的重点在于提示，所以一定要醒目。除提示性质外，不要轻易使用加粗。如果目的是醒目，可以使用 斜体。

---

8. 段落布局

1. 段落的开头不要使用空格缩进，方便自定义样式
2. 段落的主题一定要分明，一定要区分每一个段落的主题思想
3. 一个段落遇到了多个分支描述点，一定要使用有序列表
4. 不要在有序或者是无序列表中使用图片

---

注意：为了演示效果，文中加了转义符，实际使用的语法可以直接看清楚。