写Markdown文档注意点

我在写博客的这几天意识到了一个相当严重的问题, 就是文档样式在各个平台的差异性导致视觉效果太low. 痛定思痛之下我把我总结的几点记录下来, 方便大家不要再次踩坑.

大纲如下:

1. 区别全/半角符号
2. 图片的使用
3. 外连接的使用
4. 列表的使用
5. 表格的使用
6. 标题拆分, 一定要使用大纲
7. 提示性语句一定要加粗
8. 注意段落分布

1. 区别全/半角符号

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

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

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

   Hello, world! buteaful
   世界, 你好

2. 图片的使用

markdown 中对图片的引用包括以下几种:

1. 直接在需要引入的位置, 例如: ![alt 属性值](图片地址)
2. 使用图片变量, 例如: [avatar]:(图片地址). 在文档中使用变量名, 例如: [avatar]
3. 直接使用<img />html标签, 使用场景是需要定义图片大小

注意: 我推荐第二种
原因无它, 结构清晰, 一目了然, 定位准确, 文档美观. 将所有的图片变量全部放在文档底部, 包括网址链接 注意: 不要使用img标签去设置图片的大小

3. 外链接的使用

markdown 中使用外链接也有多种方式, 如下:

1. 直接使用链接, 例如: <https://baidu.com>
2. 使用a标签, 例如: <a href='https://www.baidu.com' target='_blank' >baidu</a>
3. 在文档中直接使用, 例如: 我要去[百度](https://baidu.com)一下啦
4. 使用变量, 例如: [baidu.com]

注意: 我推荐使用第四种

4. 列表的使用

markdown 中也分为有序和无序列表两种, 分别对应了html中的ol与ul

1. 有序列表的语法: 以数字开头, 紧接着一个.号, 之后空格
2. 以 +, -, * 开头紧接空格

注意: 这个要结合使用, 第一级别尽量使用有序列表

5. 表格的使用

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

注意: 使用表格做到职责分明, 有子属性的字段尽可能的拆分, 放到下一个表格之中
注意: 表格样式居中, 这个不强求, 我是觉得居中对齐好看

6. 标题拆分

你也许会遇到这么一种情况, 在一个段落之中, 使用了标题, 有普通的文本, 还有图片, 怎么处理一下, 样式上才会更好的兼容, 或者说是融洽. 如下:

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

这一段的结构不好, 太粗糙了. 我试过在微信公众平台和前台的渲染中使用, 样式上的问题还是比较多, 比如我在博客里面提到了, 全局样式覆盖的问题.

改进:

## 标题

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

现在要插入图片了！

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

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

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

7. 提示性语句一定要加粗

提示性语句的重点在于提示, 所以一定要醒目, 老外的醒目是大写, 这里我就用加粗吧. 例如: **注意: **, 所以除了提示性质之外的语句, 不要轻易的使用加粗, 如果目的是为了醒目, 可以使用 斜体

8. 段落的布局是展示样式的关键

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

注意: 为了演示效果, 我加了转义符, 使用的语法可以直接看清楚