MarkDown文档编写规范

by SkylineBin

1.选用Markdown原因及应用背景

2.推荐使用的Markdown写作软件

Markdown文件可以用任何编辑器编写,但一般的编辑器不能解析文件。本项目主要是优秀方法整理和技术总结应该也用不到特别复杂的语法,但是排版对文档逻辑的展现有辅助作用,所以还是推荐使用可以预览的Markdown编辑器。下面推荐两款比较好用的软件:

以上两款软件都支持文件目录,可以很方便创建整理文件。
注:个人更喜欢Atom,看起来更简洁,操作也更简单。但VSCode会更稳定。

3.Markdown基本语法及举例

前面有提到,Markdown的语法很简单,用起来也会很顺手。先推荐几篇快速上手的文章,这些文章会更完整,大概十分钟左右可以上手编辑文档。之后会针对常用的Markdown语法给出参考。

Markdown常用语法

3.1 Markdown标题

Markdown文档中使用每行开头的 # 号来判定是否为标题,一共六级,对应 # 号的个数:

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

需要注意的是,# 号与 后面标题名称之间应该有空格。

3.2 Markdown换行与段落

Markdown里可以使用回车换行,但 前提 是上一行的末尾要多余两个空格。这样Markdown才可解析出正确的指令。
Markdown中支持HTML里的< br / > 换行符,但一般不使用这个。

3.3 Markdown图片插入与链接引用

Markdown中使用[ ]和( )构成的符号来引入连接或者插入图片。
插入链接 只需要使用 [ 显示文本 ]( 链接地址 ) 这样的语法

[Github](https://github.com)

即:Github
插入图片 只需要使用 ![图片标签](图片链接地址) 这样的语法

![This is a Github Logo](https://assets-cdn.github.com/images/modules/logos_page/GitHub-Logo.png)

即可插入下图:

This is a Github Logo.

本项目中插入图片规范如下:

3.4 Markdown粗体和斜体

对于需要强调的部分,常使用 粗体斜体 来以示区别。粗体部分使用两个 * 号包围来引入,斜体部分使用一个 * 号包围来引入。

这是 **粗体** ,这是 *斜体*.

3.5 Markdown中代码引用

代码引用 可能是之后本项目使用较多的一部分。Markdown中使用键盘上英文输入法下,数字1左边的小点 ` 来作为代码引入的开始。使用三个 `来开始引用代码,三个 ` 结束代码引用。前三个 `的后面可以标注代码的语言,也可以不用标注。

//标注了代码类型的好处是可以给出关键字高亮
//以下是java实现快速排序的递归形式算法
public static void quickSort(int[] arr){
    qsort(arr, 0, arr.length-1);
}
private static void qsort(int[] arr, int low, int high){
    if (low < high){
        int pivot=partition(arr, low, high);        //将数组分为两部分
        qsort(arr, low, pivot-1);                   //递归排序左子数组
        qsort(arr, pivot+1, high);                  //递归排序右子数组
    }
}
private static int partition(int[] arr, int low, int high){
    int pivot = arr[low];     //枢轴记录
    while (low<high){
        while (low<high && arr[high]>=pivot) --high;
        arr[low]=arr[high];             //交换比枢轴小的记录到左端
        while (low<high && arr[low]<=pivot) ++low;
        arr[high] = arr[low];           //交换比枢轴小的记录到右端
    }
    //扫描完成,枢轴到位
    arr[low] = pivot;
    //返回的是枢轴的位置
    return low;
}

代码引入具体实现如下图所示:

Markdown中代码引入

3.6 Markdown中分隔线及转义符号

Markdown中使用三个 * 号来画出一条分隔线,效果如下所示: *** Markdown中的符号转义使用 反斜杠 \ 来帮助插入普通的符号。

3.7 Markdown中插入公式

原生的 Markdown 中其实没有公式的这一项的,但是很多替代的解决方案。
例如,可以使用图片的方式来引入公式:

<img src="http://latex.codecogs.com/png.latex?f_%7B1min%7D%20%3D%20min%5Cleft%20%5C%7B%20%5Csum_%7Bi%3D1%7D%5E%7BN%7D%5Cleft%20%28%20T_%7Bc%7D-T_%7Bsi%7D%20%5Cright%20%29%5E%7B2%7D%20%5Cright%20%5C%7D" style="border:none;">

以此得到下图的公式:

或者是用引入图片的方式:

![formula one](http://latex.codecogs.com/png.latex?f_%7B1min%7D%20%3D%20min%5Cleft%20%5C%7B%20%5Csum_%7Bi%3D1%7D%5E%7BN%7D%5Cleft%20%28%20T_%7Bc%7D-T_%7Bsi%7D%20%5Cright%20%29%5E%7B2%7D%20%5Cright%20%5C%7D)

这两个其实都是使用 在线公式编辑器 codecogs 实现的。
类似的平台还有 forkosh

第二种可以使用 引入写公式的 js 文件:

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=default"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>

可以按照对应的js 规则写公式即可。

个人使用第一种以图片的形式引入更多,这种方式可以引入比较好看的 Latex 格式的公式图片。

3.8 Markdown中页面内部跳转

对于长篇文章,页面内部跳转可以方便读者阅读,效果较好。
检索了 Markdown 里页面内部跳转的实现形式,基本都是使用 a 标签的锚点这种方式:

<span id="anchor">需要跳转到的锚点</span>

<!-- 引用锚点时 -->
[跳转到锚点处](#anchor)

例如,可以点击 回到顶部

以上为本项目文档的Markdown编辑规范,原文档是为实验室工作基础知识整理的文档规范,但是实验室同学们觉得这个太麻烦了,我就放在这里了,毕竟也是自己花费了一些心思整理的!