Python-Markdown 库中,有一个插件 Fenced Code Blocks 。使用它能够支持 PHP Markdown ExtraGitHub Flavored Markdown 格式的代码块。

我对 Fenced Code Blocks 插件进行了扩展,使其可以支持以下功能:

  1. 注释的代码块;
  2. Graphviz 支持。

扩展过的插件,名为 Fenced Code Extra ,暂时托管于我的 wpcmd 项目中。

1. 注释的代码块

Markdown 本身是不支持注释的。这个扩展功能,就是让代码块能够支持注释。

举个简单的例子,这段 Markdown 代码:

## graph

1
2
3
4
5
graph pic1 {
a -- b
a -- b
b -- a [color=blue]
}
![Graphviz chart 2294-graphviz-0.png](/uploads/2015/06/2294-graphviz-0.png)

会被渲染成这样:

1
2
<h2>graph</h2>
<p><img alt="Graphviz chart 2294-graphviz-0.png" src="/uploads/2015/06/2294-graphviz-0.png" /></p>

也就是说,在代码块开始指示符后面加上 # 符号( # 后面可以带有其他字符),整个代码块就变成了注释,不会被渲染成 HTML。

2. Graphviz 支持

在上一篇文章 GraphViz 简易教程 中,我介绍了 Graphviz 这个有趣且有用的工具。现在使用 Fenced Code Extra ,可以将位于 Markdown 中的 Graphviz 代码自动转换成图片,同时支持在 Markdown 源文件中仅保存图片、仅保存代码或者同时保存代码和图片。

2.1 graphviz 范例

例如,有这样一段 Markdown ,保存在变量 txt 中:

## graph

1
2
3
4
5
graph pic1 {
a -- b
a -- b
b -- a [color=blue]
}

让我们使用 Markdown 库渲染它:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import markdown
def _get_extra_output(md, name):
extra_output = getattr(md, 'fenced_code_extra_output', None)
if not extra_output:
return None
return extra_output.get(name)
md = markdown.Markdown(
extensions=[
'fenced_code_extra',
],
extension_configs={
'fenced_code_extra':{
'graphviz':{
'OUTPUT_DIR':'/home/wp/upload',
'BASE_URL':'/uploads',
'NAME_PRE':'graphviz'},
}
}
)
html = md.convert(txt)
graphviz = _get_extra_output(md, 'graphviz')
if graphviz:
mdtxt = graphviz['text']

在上面,必须加入 markdown 的扩展参数,其中包含 fenced_code_extra 插件的 graphviz 设置。

  • OUTPUT_DIR 指图像的输出文件夹;
  • BASE_URL 指输出的图像被转换成的基础 URL;
  • NAME_PRE 指输出文件名的前缀,可以设置成空字符串。

调用之后, html 的值将为:

1
2
<h2>graph</h2>
<p><img alt="Graphviz chart graphviz-0.png" src="/uploads/graphviz-0.png" /></p>

mdtxt 的值为:

## graph

![Graphviz chart graphviz-0.png](/uploads/graphviz-0.png)

mdtxt 是对 graphviz 代码进行处理之后的 Markdown 源码,可以将这个源码保存下来以便重复使用。

2.2 生成的文件名

文件名的命名规则是 NAME_PRE-NAME-NUM.TYPE ,下面一一介绍:

  • NAME_PRE 在 Markdown 的扩展参数中,上面有范例;
  • NAME 在 graphviz 块开始的时候指定(下文详述),在上面的范例中并没有明确指定 NAME 的值,因此默认为空字符串;
  • NUM 源码中可能有多个 graphviz 块,这样生成的文件也可能有多个。为了避免重名,NUM 是自动计算出的编号,从0开始;
  • TYPE 在 graphviz 块开始的时候指定(下文详述),在上面的范例中并没有明确指定 TYPE 的值,因此默认为 png

2.3 config

让我们详细看看 graphviz 代码块支持的配置参数:

## graph

config="name=pic1,type=svg,show=codeandimage"
1
2
3
4
5
graph pic1 {
a -- b
a -- b
b -- a [color=blue]
}

代码起始符号加上 graphviz 指示这是一个包含 graphviz 代码的块。graphviz 后面的 _ 之后的内容代表 graphviz 的渲染程序,若不指定任何渲染程序,将默认使用 dot

config 中可以包含三个值:

  • name 和上文中提到的文件名 NAME 相关。若不设置,将使用空字符串;
  • type 生成的图像类型,和上文中提到的 TYPE 相关,这里是 支持的格式 列表。若不设置,将使用 png
  • show 指示是仅显示图像(image),仅显示代码(code)还是都处理(codeandimage)。若不设置,将使用 image

用与范例相同的代码处理之后,得到的 html 的值内容为:

1
2
3
4
5
6
7
8
9
10
<h2>graph</h2>
<div class="codehilite">
<pre>graph pic1 {
a -- b
a -- b
b -- a [color=blue]
}
</pre>
</div>
<p><img alt="Graphviz chart graphviz-pic1-0.svg" src="/uploads/graphviz-pic1-0.svg" /></p>

mdtxt 的值为:

## graph

1
2
3
4
5
graph pic1 {
a -- b
a -- b
b -- a [color=blue]
}
![Graphviz chart graphviz-pic1-0.png](/uploads/graphviz-pic1-0.png)

注意,上面的 Markdown 代码中用来指示 graphviz 代码的字段以及 config 信息都已经被删除。

(全文完)

留言

2015-06-11
次访问