谷歌公司推荐的 Markdown 书写格式规范

Markdown 之所以伟大，很大部分原因是因为它只需要编写简单的纯文本，却能够输出漂亮的格式。为了管理好众多的 markdown 文件，你的 Markdown 文件应该尽可能简单并且风格保持一致。

因此我们希望我们的 markdown 文件需要达到以下3个小目标：

1. 源码是易读的，并且是轻便的；
2. markdown 文件内容要好维护；
3. 语法要简单，并且容易记住；

文档布局

通常情况，下面的布局就很不错，如果不满意，可以在此基础上进行修改：

# 文档的题目

作者：程序员说IT
时间：2021-06-23 10:28

内容简介...

[TOC]

## 主题

主题的内容...

## 参考

* https://....

1. 文档的题目：文章的题目应该是一级标题，理想情况下应该与文件名相同。
2. 作者名称：是可选的，如果您想声明该文档的所有权，请在标题下添加您自己。
3. 内容简介：1 - 3个句子就可以了，对文章的简单介绍，方便读者一眼就知道文章的内容。
4. [TOC]：有些软件会识别这个字符，自动插入文档目录到这位置。
5. 主题：主题是介绍文字的每一个部分的内容，必须是二级标题。
6. 参考：把文章的参考链接、参考文献放在这里。

行的长度不要太长

如果内容太长的话应该换行，尽量不要在一行里写太长的内容，否则不方便源码阅读。

换行

不要通过在行末加2个空格的方式进行换行，因为有些ide会自动去空格，导致换行失效，正确的做法应该是用反斜线。

标题

要用ATX风格的标题

带有=的标题不好维护，容易混淆，不要使用。

## 标题2

在标题之间需要插入空行

这样在阅读源码的时候比较容易阅读。

内容...

## 标题2

内容...

列表

长列表要用惰性数字编号

因为这样不需要去维护顺序，不然增加或者调整顺序的话，要不停地修改编号。惰性数字编号markdown在渲染的时候，会自动地生成顺序的编号。

1.  动物
1.  水果
    1.  葡萄
    1.  橘子
1.  植物

如果是短的编号，可以使用顺序编号。

1.  葡萄
2.  橘子
3. 苹果

列表嵌套要用4个空格

有序和无效列表嵌套的空格应该用4个空格。

1.  水果
    1.  葡萄

代码

行内代码

经常用于转义一些markdown的特殊字符，以及用于一行内的代码显示，例如：

函数`in_array()`是用于判断某个元素是否存在于数组当中。

代码块

如果代码量超过一行的话，这个时候就需要用代码块了，需要声明代码类型，以至于更好地解析和高亮该代码内容：

```php
$str = 'Hello World';
echo $str;
```

如果不想指明代码语言的话，也可以使用4个空格缩进的方式，有时候这种方式反而能使源码的变得更加清晰，例如编写简单的片段的时候这种方式就很好用，例如：

首先运行：

    php think generate:controller
    
然后运行：

    php think generate:model
    
最后运行：

    php index.php

对于很长的代码，需要转义换行符号，不然的话执行代码的时候，后面的选项将不会生效：

```shell
/configure \
--prefix=/usr/local/lnmp/php7.2 \
--exec-prefix=/usr/local/lnmp/php7.2 \
--with-config-file-path=/usr/local/lnmp/php7.2/etc  \
--with-libdir=lib64
```

列表中使用代码块：

要确保代码块4个空格缩进，这样不会破坏列表，例如：

*   编译

    ```shell
    make
    ```

*   安装

    ```shell
    make install
    ```

或者用缩进的方式书写代码也可以，这个时候代码前面要有8个空格，例如：

*   编译.

        make

*   安装.

        make install

链接

长链接很容易使得一行字变得很长，所以尽量使链接变得短一点，例如：

有关更多信息，请参阅 [参考文档](document.md)。

使用列表替代表格

markdown中的表格比较适合短篇幅的，如果内容比较长的话，很难维护，如下所示就很混乱：

水果 | 属性 | 注意
--- | --- | --- | ---
苹果 | [多汁的](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | 可以保持健康.
香蕉 | [方便的](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | 有很多维生素.

这个时候最好用列表替代表格：

## 水果

### 苹果

* [多汁的](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)

* 可以保持健康.

### Banana

* [方便的](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)

* 有很多维生素

最后说一点

尽量在文档中使用原生的markdown语法，少使用html来书写。