Markdown使用笔记

Posted 2022-12-06 yfyzwr

本文的实现编辑器是MarkdownPad2。

本文主要的参考文章链接如下所示:

• Markdown 语法说明(简体中文版)
• 献给写作者的 Markdown 新手指南

简介与说明

Markdown 语法的目标是：成为一种适用于网络的书写语言。

Markdown 不是想要取代 html，甚至也没有要和它相近，它的语法种类很少，只对应 HTML 标记的一小部分。Markdown 的理念是，能让文档更容易读、写和随意改。

不在Markdown涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写。要制约的只有一些HTML区块元素（比如<div>、<table>、<pre>、<p>等标签），必须在前后加上空行与其它内容区隔开，还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。

不同的编辑工具可能会在细节处有不同的实现，另外推荐在线的markdown编辑器Dillinger。

本文会一直处于不断更新完善的过程中

Markdown语法

段落和换行

Markdown普通段落是由一个或多个连续的文本行组成，段落的前后要有至少一个的空行。普通段落不应该用空格或制表符来缩进。

「由一个或多个连续的文本行组成」这句话其实在暗示Markdown允许段落内的强迫换行（插入换行符）。在需要换行的地方插入两个空格再回车，即可实现换行。

标题

Markdown支持两种标题的语法，类 Setext 和类 atx 形式，推荐使用类 Atx 形式。

类Atx形式则是在行首插入1到6个 # 符号，对应着标题1~6阶，使用例程如下：

#第一阶标题      或者       #第一阶标题#
##第二阶标题     或者       ##第二阶标题##

可以选择性地「闭合」类atx样式的标题，当然这纯粹只是出于美观考虑，若是觉得这样看起来比较舒适，就可以在行尾也加上 # 符号，而行尾的 # 数量也不必和开头一致（行首的 # 字符数量决定标题的阶数）

区块引用

Markdown标记区块引用是使用 > 符号的引用方式。在Markdown文件中建立一个区块引用，就需要自己先断好行，然后在每行的最前面加上 > 符号。

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

区块引用可以嵌套（即引用内的引用），只要根据层次加上不同数量的 > 符号。

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

引用的区块内也可以使用其他的 Markdown 语法，包括标题、列表、代码区块等。

> ##这是标题
> 
> 1.   这是第一行列表项
> 2.   这是第二行列表项
> 
> 给出一些例子代码
> 
>     return shell_exec("echo $input | $markdown_script");

列表

Markdown支持有序列表和无序列表。

无序列表使用星号*、加号+或是减号-作为列表标记。

- Red
- Green     或者是将减号换成加号、星号
- Blue

有序列表则使用数字紧接一个英文句点（注意英文据点）。

1. Bird
2. McHale
3. Parish

列表条目的标记通常是放在最左边，但其实也可以缩进最多3个空格，而条目标记的后面则一定要接着至少一个空格或制表符。

列表条目可以包含多个段落，每个条目下的段落都必须缩进4个空格或是1个制表符。新的段落在缩进一个制表符的基础上，还需要与前一段落间隔一个空行。

1. 第一条目的第一段

    新段落要缩进一个制表符，并与前一段落间隔一个空行

2. 第二条目的第一段

如果想要在列表条目内放进区块引用，那 > 符号就需要缩进4个空格或是1个制表符。

* A list item with a blockquote:
    > This is a blockquote.
    > 
    > inside a list item.
* B other list item

如果想要在列表条目内放进代码区块，该代码区块就需要缩进两次，也就是8个空格或是2个制表符。在MarkdownPad2编辑器中还另外要求代码区块与列表条目之间间隔一个空行。

* A list item with a blockquote

        <code Block1> 
        <code Block2>
* B other list item

代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落的方式去排版，而是照原来的样子显示，Markdown会用<pre>和<code>标签来把代码区块包括起来。

要在Markdown中建立代码区块很简单，只要简单地缩进4个空格或是1个制表符就可以实现。要求代码区块与普通段落之间间隔一个空行

Here is an example of C:

    int main(int argc, char* args[])
    
        return 0;
    

某个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

代码区块中，一般的Markdown语法符号不会被转换（例如[]便只是[]而已），这样就可以很容易地以 Markdown语法撰写Markdown语法相关的文件。

行内代码

如果要标记小段的行内代码，你可以用反引号`把它包围起来。

Use the `printf()` function.

如果要在代码区段内插入反引号，可以用多个反引号来开启和结束代码区段。

``There is a literal backtick (`) here.``

代码区段的起始和结束端都可以放入一个空格，起始端后面一个，结束端前面一个，这样就可以在代码区段的一开始就插入反引号。

A single backtick in a code span: `` ` ``  
A backtick-delimited string in a code span: `` `foo` ``

分割线

在一行中用三个以上的星号、减号、下划线来建立一条分割线，行内不能有其他东西。这些符号之间不能有其他内容，但是可以插入空格。

***
---
___

链接

Markdown支持两种形式的链接语法：行内式和参考式两种形式。

要建立行内式的链接，链接文字需要用方括号[]来标记，只要在方括号后面紧接着圆括号并插入网址链接即可。如果还想要加上链接的title文字，只要在网址后面，用双引号把title文字包起来即可。

点击如下链接即可转到[百度](https://www.baidu.com/ "百度首页")

登录[Google](http://www.google.com.hk/ "Google home")请点击

如果是想要链接到本地主机的资源，可以使用相对路径。

想看[我的照片](/about/my.img)吗？

参考式的链接是在链接文字的方括号后面再接上另一个方括号，然后在第二个方括号里面填入用以辨识链接的标记。

最后在文件的任意处，可以把这个标记的链接内容定义出来。链接内容定义的形式为：

• 方括号（前面可以选择性地加上至多三个空格来缩进），里面输入链接辨识标记（链接辨识标记可以有字母、数字、空白和标点符号，但是并不区分大小写）
• 接着一个冒号
• 接着一个以上的空格或制表符
• 接着链接的网址
• 选择性地接着title内容，可以用单引号、双引号或是括弧包含

参考式链接的使用例程如下：

点击如下链接即可转到[百度][1]  
登录[Google][2]请点击

[1]: https://www.baidu.com/ "百度首页"  
[2]: http://www.google.com.hk/ "Google home"

使用Markdown的参考式链接，可以让文件更像是浏览器最后产生的结果，让你可以把一些标记相关的元数据移到段落文字之外，就可以增加链接而不让文章的阅读感觉被打断。

隐式链接标记让你可以省略指定链接标记，在这种情形下，链接标记会视为等同于链接文字。

点击如下链接即可转到[百度]   
登录[Google]请点击

[百度]: https://www.baidu.com/ "百度首页"  
[Google]: http://www.google.com.hk/ "Google home"   

强调

Markdown使用星号 * 和下划线 _ 作为标记强调字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围的斜体显示，用两个* 或 _ 包起来的话，则会被转成<strong>包围的粗体显示。

*斜体显示*  
_斜体显示_  
**粗体显示**  
__粗体显示__
***斜体+粗体显示***  
___斜体+粗体显示___

如果在 * 或 _ 的两边都有空白的话，它们就只会被当成普通的符号。
如果要在文字前后直接插入普通的星号或底线，可以用反斜线。

图片

Markdown使用一种和链接很相似的语法来标记图片，同样也允许两种样式：行内式和参考式。

图片的行内式语法详细叙述如下：

• 一个惊叹号!
• 接着一个方括号，里面放上图片的替代文字
• 接着一个普通括号，里面放上图片的网址
• 最后还可以选择性地用引号包住并加上title文字

行内式图片的使用例程如下：

![Alt text](/path/to/img.jpg "Optional title")

参考式图片的使用例程如下：

![Alt text][id]  
[id]: url/to/image  "Optional title attribute"

自动链接

Markdown支持以比较简短的自动链接形式来处理网址和电子邮件信箱，只要是用尖括号包起来，Markdown就会自动把它转成链接。

<https://www.baidu.com/>  
<[e-mail]>

反斜杠

Markdown可以利用反斜杠来插入一些在语法上有其它特殊意义的符号。Markdown支持在以下这些符号的前面加上反斜杠来帮助插入普通的符号：

• \\ 反斜线
• ` 反引号
• * 星号
• _ 下划线
• 花括号
• [] 方括号
• () 括弧
• # 井字号
• + 加号
• - 减号
• . 英文句点
• ! 惊叹号

Markdown Extra 语法

相关说明

参考文档如下所示：

• PHP Markdown Extra

对于Markdown Extra的语法实现而言，这些语法是原生的Markdown语法的扩展。这些扩展语法的实现在不同的Markdown编辑器中可能会不同。

想要在MarkdownPad2中使用Extra语法，需要将其升级为Pro版本。然后还需要对软件进行设置：Tools->Options->Markdown->Markdown Processor

表格

Markdown Extra对于表格有自己的语法。

• 第一行是列标题
• 第二行是强制存在的分隔线，位于列标题和内容之间
• 其后每一行都是表格的内容
• 每一列之间通常是由管道符号 | 来分隔

表格基本示例如下：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

也可以根据自己的喜好在表格每一行的开头和结尾各加上管道符号。

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

注意：表格的每行至少需要有一个管道符号，才能被Markdown Extra的语法正确解释。这就意味着想要创建只有一列的表格，需要在开头或（与）结尾使用管道符号。

可以在分隔行添加冒号来为每一列指定排列方式。

• 冒号在分隔行的左边，表示该列左对齐
• 冒号在分隔行的右边，表示该列右对齐
• 分隔行的左右都有冒号，表示该列居中

设置排列方式的示例如下：

| Item      | Value |
| :-------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

在表格的每个单元格中同样可以使用前述的Markdown语法。

定义列表

定义列表由条目和该条目的定义构成，其结构类似词典的条目。

简单的定义列表由当行的条目、后接冒号以及对应的定义而构成。

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

• 新的条目必须通过空白行来与前面条目的定义相分隔。
• 冒号后面必须有至少一个空格或者是有一个制表符。
• 同一条目可以对应有多个定义。
• 多个条目可以共用相同的定义。

更多使用示例如下：

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.
:   An American computer company.

Banana
Orange
:   The fruit of an evergreen tree of the genus Citrus.

脚注

脚注通常由两部分组成：位于右上角的标识、位于文档末尾的列表中的具体定义。

脚注的使用示例如下：

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

      That's the second paragraph.

方括号中的不一定就是数字，它可以是任意的字符或者字符串。

HTML语法的嵌套

字体设置

设置字体的标签是<font> 标签。

<font color=#ff0000 size=3 face="微软雅黑">文字颜色、大小、字体的设置</font>

背景设置

由于style标签和标签的style属性都被和谐（这让Markdown虽然有HTML的躯体，却没有HTML的灵魂），所以这里只能是借助table, tr, td等表格标签的bgcolor属性来实现背景色的功能。

<table><tr><td bgcolor=#00FFFF>背景色的设置</td></tr></table>

首行缩进

如果想要安装中文的书写习惯，在每段的首行缩进两个字符，可以在段首添加如下字符：

       书写正文