文档写作工具链之二：Markdown风格文档

什么是 Markdown?

Markdown 是一种文本格式。你可以用它来控制文档的显示。使用 Markdown，你可以创建粗体的文字，斜体的文字，添加图片，并且创建列表等等。基本上来讲，Markdown 就是普通的文字加上 # 或者 * 等符号。

在VSCode中可以通过Markdown Preview插件可以实时预览 markdown文档

语法说明

标题

# 这是 <h1> 一级标题
## 这是 <h2> 二级标题
### 这是 <h3> 三级标题
#### 这是 <h4> 四级标题
##### 这是 <h5> 五级标题
###### 这是 <h6> 六级标题markdown

强调

 *这会是 斜体 的文字*
_这会是 斜体 的文字_

**这会是 粗体 的文字**
__这会是 粗体 的文字__

_你也 **组合** 这些符号_

~~这个文字将会被横线删除~~markdown

列表

无序列表
- Item 1
- Item 2
  - Item 2a
  - Item 2bmarkdown

有序列表
1. Item 1
1. Item 2
1. Item 3
   1. Item 3a
   1. Item 3bmarkdown

添加图片

![GitHub Logo](/images/logo.png)
Format: ![Alt Text](url)

链接

[GitHub](https://github.com)
Format: [Text](url)

引用

正如 Kanye West 所说：

> We're living the future so
> the present is our past.markdown

分割线

如下，三个或者更多的

---

连字符

---

星号

---

下划线

行内代码

`行内代码`

代码块

你可以在你的代码上面和下面添加 ``` 来表示代码块。

[1]语法高亮

你可以给你的代码块添加任何一种语言的语法高亮:

例如，给 ruby 代码添加语法高亮：ruby

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

[2]代码行数

如果你想要你的代码块显示代码行数，只要添加 line-numbers class 就可以了：javascript {.line-numbers}

例如：

function add(x, y) {
  return x + y
}

[3]高亮代码行数

你可以通过添加 highlight 属性的方式来高亮代码行数：

javascript {highlight=10}
javascript {highlight=10-20}
javascript {highlight=[1-10,15,20-22]}

任务列表

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete itemmarkdown

[x] @mentions, #refs, links, formatting, and ~~tags~~ supported
[x] list syntax required (any unordered or ordered list supported)
[x] this is a complete item
[ ] this is an incomplete itemmarkdown

表格

 First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second columnmarkdown

First Header	Second Header
Content from cell 1	Content from cell 2
Content in the first column	Content in the second columnmarkdown

上标

30^th^

30^th

下标

H~2~Omarkdown

H₂Omarkdown

脚注

Content [^1]

[^1]: Hi! This is a footnotemarkdown

标记

==marked==

marked

CriticMarkup

CriticMarkup 缺省是禁用的，你可以通过插件设置来启动它。
有关 CriticMarkup 的更多信息，请查看 CriticMarkup 用户指南.

这里有 5 种基本语法：

添加 {++ ++}
删除 {-- --}
替换 {~~ ~> ~~}
注释 {>> <<}
高亮 {== ==}{>> <<}

CriticMarkup 仅可用于 markdown-it parser，不与 pandoc parser 兼容。

注释

[1]html标签注释

既然Markdown内嵌html语法，那么就可以用可以用隐藏的html标签。

注意：需要在前面空一行

<div style='display: none'>
哈哈我是注释，不会在浏览器中显示。
我也是注释。
</div>

[2]html注释

既然支持html语法，那也支持html注释。

<!--哈哈我是注释，不会在浏览器中显示。-->

<!--
哈哈我是多段
注释，
不会在浏览器中显示。
-->

[3]hack方法

hack方法就是利用markdown的解析原理来实现注释的。

一般有的markdown解析器不支持上面的注释方法，这个时候就可以用hack方法。

hack方法比上面2种方法稳定得多，但是语义化太差。

[comment]: <> (哈哈我是注释，不会在浏览器中显示。)
[comment]: <> (哈哈我是注释，不会在浏览器中显示。)
[comment]: <> (哈哈我是注释，不会在浏览器中显示。)
[//]: <> (哈哈我是注释，不会在浏览器中显示。)
[//]: # (哈哈我是注释，不会在浏览器中显示。)
其中，这种方法最稳定，适用性最强：

[//]: # (哈哈我是注释，不会在浏览器中显示。)

这种方法最可爱，超级无敌萌啊：

[^_^]: # (哈哈我是注释，不会在浏览器中显示。)

数学公式

Markdown Preview Enhanced 使用 KaTeX 或者 MathJax 来渲染数学表达式。

KaTeX 拥有比 MathJax 更快的性能，但是它却少了很多 MathJax 拥有的特性。你可以查看 KaTeX supported functions/symbols 来了解 KaTeX 支持那些符号和函数。

默认下的分隔符：
$...$ 或者 \(...\) 中的数学表达式将会在行内显示。
$$...$$ 或者 \[...\] 或者 ```math 中的数学表达式将会在块内显示。

时序图

Digital timing diagram rendering engine
Markdown Preview Enhanced 使用 WaveDrom 来渲染 digital timing diagram.
wavedrom 代码块中的内容将会被 WaveDrom 渲染。

{ signal: [
  {    name: 'clk',   wave: 'p..Pp..P'},
  ['Master',
    ['ctrl',
      {name: 'write', wave: '01.0....'},
      {name: 'read',  wave: '0...1..0'}
    ],
    {  name: 'addr',  wave: 'x3.x4..x', data: 'A1 A2'},
    {  name: 'wdata', wave: 'x3.x....', data: 'D1'   },
  ],
  {},
  ['Slave',
    ['ctrl',
      {name: 'ack',   wave: 'x01x0.1x'},
    ],
    {  name: 'rdata', wave: 'x.....4x', data: 'Q2'},
  ]
]}