文档写作工具链之二：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

    

上标

        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‘},
  ]
]}

    

参考资料

• 在Markdown中写注释
• Github Mastering Markdown

原文：https://www.cnblogs.com/albert-8/p/12638873.html