最近写文档和写博客都开始用 markdown ，其中博客用得是Pelican，文档用Mkdocs。它们俩都用python-markdown模块来处理 markdown 文件。而这个模块支持扩展，可以大大提升 markdown 的表现力：
下面介绍一些我用过的比较好的扩展。
1、英文和中文之间自动插入空格
插件markdown-cjk-spacing可用于在中文字符和英文字符之间插入空格。
一般英文单词之间会有空格，但英文单词和中文之间没有空格挤在一期，在视觉上特别不好看。这个插件可以帮忙自动插入空格，中英文混排会好看很多。
这是第三方插件，需要手工安装：
sudo pip install markdown-cjk-spacing
插件的实现有点小问题，不会添加空格到<span>english</span>中文。我小小修改了一下，在作者修正之前可以用我这个：
sudo pip install https://github.com/zhangzq/markdown_cjk_spacing/archive/master.zip
2、attr_list 设置 HTML 属性
attr_list 扩展可用于设置 HTML 属性。
比如### title {:#id .class}会被转换为<h3 id="id" class="class">title</h3>。这可以用于设置css style以及引用瞄点。
3、Admonition 生成特殊代码块
admonition 扩展可生成一些提示，警告代码块。
比如下面的代码：
!!! note "admonition的用法"
admonition可用于生成代码块，配合设置css，可生成非常漂亮的页面。
!!! warning
admonition代码块以`!!! `开头，后接info或warning或任何你想要的单词和单词列表，这些单词和单词列表将作为该显示块的class，通过配置这些class的css，便能自定义很多特殊的显示块。
class后面是双引号包括的显示块表头，如果不想显示表头，可写`""`。
显示的结果为：
admonition 的用法
admonition 可用于生成代码块，配合设置 css ，可生成非常漂亮的页面。
Warning
admonition 代码块以!!!开头，后接 info 或 warning 或任何你想要的单词和单词列表，这些单词和单词列表将作为该显示块的 class ，通过配置这些 class 的 css ，便能自定义很多特殊的显示块。
class 后面是双引号包括的显示块表头，如果不想显示表头，可写""。
该插件需要主题配合。若主题没有内置式样，需要主动增加css：
.admonition {
padding: 0.75em;
margin-bottom: 1.5em;
background: #e7f2fa;
}
.admonition-title {
color: #fff;
font-weight: bold;
display: block;
background: #6ab0de;
margin: -0.75em;
padding: 0.5em 0.75em;
margin-bottom: 0.75em;
}
.admonition-title:before {
margin-right: 0.25em;
font-family: "FontAwesome";
display: inline-block;
font-style: normal;
font-weight: normal;
text-decoration: inherit;
content: "\f040";
}
.warning {
background: #ffedcc !important;
}
.warning .admonition-title {
background: #f0b37e !important;
}
.warning .admonition-title:before {
content: "\f071" !important;
}
.admonition p:last-child, .admonition ul:last-child .admonition ol:last-child {
margin-bottom: 0;
}
4、Latex 数学公式
借助于 mathjax ，现在在 markdown 中插入数学公式已经是标配。第三方扩展mdx用于处理 markdonw 文件里的数学公式。
该插件需要安装：
sudo pip install python-markdown-math
5、配置
5.1、mkdocs 中配置 markdown 扩展
在mkdocs.yml中配置：
markdown_extensions:
- admonition:
- mdx_math:
add_preview: true
enable_dollar_delimiter: true
- toc:
permalink: true
- markdown_include.include:
base_path: /home/zhangzq/room
- markdown_cjk_spacing.cjk_spacing:
- attr_list:
5.2、pelican 中配置 markdown 扩展
在pelicanconf.py中增加配置：
MARKDOWN = {
"extension_configs": {
'markdown.extensions.codehilite': {'css_class': 'highlight'},
'markdown.extensions.extra': {},
'markdown.extensions.meta': {},
'markdown.extensions.attr_list': {},
'markdown.extensions.admonition': {},
'markdown_cjk_spacing.cjk_spacing': {
'segment_break': True
},
# 'mdx_math': {
# 'add_preview': True,
# 'enable_dollar_delimiter': True,
# },
},
'output_format': 'html5',
}
Q. E. D.
