pandoc中提供的markdown特殊扩展功能

1 段落

在markdown中一个分行符不会将文字拆分成两段,为了段落的拆分,你需要在段落之间插入一个空行,也即两个换行符。pandoc提供了两种额外的分行方法,分别是:

  1. 在行尾添加两个空格或者更多的空格
  2. 在后一段的段首加一个反斜杠

不过注意上面两种手段的分段方式不是创建两个p标签,而是插入一个<br />

2 Heading

2.1 Setext风格的Heading

在一行文字的下一行添加一行=(代表一级标题,即<h1>)或者-(代表二级标题,即<h2>

1
2
3
4
5
A level-one heading
===================

A level-two heading
-------------------

2.2 ATX风格的Heading

这就是常见的Heading方式,使用#符号。

pandoc要求以#开头的heading前方必须有一个空行。

2.3 Heading的ID

Heading可以使用如下的格式指定属性(html),在尾部添加

1
{#identifier .class .class key=value key=value}

注意,Hexo在使用默认的渲染引擎渲染之后,会把输出文档交给Nunjucks再渲染一遍,而在Nunjuck中`表示注释,因此`的形式会导致解析错误。目前要解决这个问题需要修改Hexo的源代码,而无法通过配置解决。

例如下面的写法可以为Heading指定id为foo:

1
2
3
4
5
6
# My heading {#foo}

## My heading ## {#foo}

My other header {#foo}
---------------

2.4 Heading的编号

注意在hexo-render-pandoc中默认是没有打开Heading编号的功能的,使用这一功能需要在博客的_config.yml(注意不是主题的)加入

1
2
3
pandoc:
extra:
number-sections: null

在Heading后面添加.unnumbered可以阻止对给定的Heading进行编号

1
2
3
4
# My heading {.unnumbered}

<!--可以简写为-->
# My header {-}

3 代码块

额外的代码块形式

1
2
3
~~~
code
~~~

这样写有一个好处,那就是中文输入法时` 符号常常无法输入,而~则没有问题。

4 行块

这是解决多行输入的问题,在行块中,换行行为会原样输出。否则会以Markdown的规则进行格式化。行块的写法为

1
2
3
4
5
6
7
8
| The limerick packs laughs anatomical
| In space that is quite economical.
| But the good ones I've seen
| So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718

下面的写法也是可以的

1
2
3
4
| The Right Honorable Most Venerable and Righteous Samuel L.
Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718

5 编号的例子列表

@这个特殊的列表符号用来做全局编号。例如

1
2
3
4
5
6
(@)  My first example will be numbered (1).
(@) My second example will be numbered (2).

Explanation of examples.

(@) My third example will be numbered (3).

这些列表可以打上标签(label)以供后续引用。

1
2
3
(@good)  This is a good example.

As (@good) illustrates, ...

6 上标和下标

1
H~2~O is a liquid.  2^10^ is 1024.

渲染出来是:

H2O is a liquid. 210 is 1024.

注意~...~^...^中间不能有空格和换行,如果不得不包含空格需要用反斜杠进行转义。

我一直蠢蠢地用html标签在做这个事情

What is the difference between >>= and >>?

7 小段的span

这个比较重要,方便内联的样式控制

1
[Small caps]{.smallcaps}

等价于

1
<span class="smallcaps">Small caps</span>

8 链接

8.1 简单链接

使用尖括号可以直接把一个URL设定成链接:

1
<https://google.com>

可以集中将URL定义在一起然后在正文中引用。

1
2
3
4
[my label 1]: /foo/bar.html  "My title, optional"
[my label 2]: /foo
[my label 3]: https://fsf.org (The free software foundation)
[my label 4]: /bar#special 'A title in single quotes'

URL也可以用尖括号包裹:

1
[my label 5]: <http://foo.bar.baz>

此时标题部分移动到下一行

1
2
[my label 3]: https://fsf.org
"The free software foundation"

注意链接的label不区分大小写。

这样写也可以:

1
2
3
See [my website][]. or see [my website]

[my website]: http://foo.bar.baz

9 Div

pandoc提供了便捷地创建<div>的方法。

1
2
3
4
5
::::: {#special .sidebar}
Here is a paragraph.

And another.
:::::

冒号的数量至少是3个。也可以缩写成

1
2
3
4
5
::::: class-of-div :::
Here is a paragraph.

And another.
:::::

这个结构可以嵌套,但是要求开头的冒号一定要对应有属性设置(不然无法判断是div的开始还是结束)

1
2
3
4
5
6
7
::: Warning ::::::
This is a warning.

::: Danger
This is a warning within a warning.
:::
::::::::::::::::::

一个div的开头和结尾的冒号数量不要求保持一致,不过为了可读性,这个需要合适的设计。

10 脚注

示例如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they
belong to the previous footnote.

{ some.code }

The whole paragraph can be indented, or just the first
line. In this way, multi-paragraph footnotes work like
multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

也可以写内联脚注:

1
2
3
Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]