Markdown 之所以伟大,很大部分原因是因为它只需要编写简单的纯文本,却能够输出漂亮的格式。为了管理好众多的 markdown 文件,你的 Markdown 文件应该尽可能简单并且风格保持一致。
因此我们希望我们的 markdown 文件需要达到以下3个小目标:
- 源码是易读的,并且是轻便的;
- markdown 文件内容要好维护;
- 语法要简单,并且容易记住;
文档布局
通常情况,下面的布局就很不错,如果不满意,可以在此基础上进行修改:
# 文档的题目
作者:程序员说IT
时间:2021-06-23 10:28
内容简介...
[TOC]
## 主题
主题的内容...
## 参考
* https://....
- 文档的题目:文章的题目应该是一级标题,理想情况下应该与文件名相同。
- 作者名称:是可选的,如果您想声明该文档的所有权,请在标题下添加您自己。
- 内容简介:1 - 3个句子就可以了,对文章的简单介绍,方便读者一眼就知道文章的内容。
- [TOC]:有些软件会识别这个字符,自动插入文档目录到这位置。
- 主题:主题是介绍文字的每一个部分的内容,必须是二级标题。
- 参考:把文章的参考链接、参考文献放在这里。
行的长度不要太长
如果内容太长的话应该换行,尽量不要在一行里写太长的内容,否则不方便源码阅读。
换行
不要通过在行末加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来书写。