Markdown 的常用扩展

作者: , 共 3199 字

最近写文档和写博客都开始用 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.

类似文章:
IT » 排版, Markdown
很久以前,我就意识到中英文混排时,英文和中文之间加一个空格之后,排版会好看很多。为此,我还专门去找了处理 Markdown 文件的插件
IT » MathJax, latex, wordpress
此插件已经不再维护,但理论上可继续使用。
阅微堂从 2014 年之后更新比较少,这之间还关停过两次。每次关停都有一些网友过问,因为有些资料还比较有用。所以,在 2018 年年初开始的关停一年之后,我又把阅微堂给重启了。
IT » LaTeX, MathJax, 数学公式
如果让我投票最优秀的开源项目,我会投给MathJax。MathJax 是一个 JavaScript 引擎,用来显示网络上的数学公式。阅微堂上所有数学公式都用 LaTex 写出,通过 MathJax 来显示。
相似度: 0.059
boost是除std外最常用的 C++库,覆盖很多常用操作。目前最新的版本是1.59.0
【流浪地球】(《科幻世界》杂志 2000 年 7 月第 7 期)。作者:刘慈欣。
最近半年, A 股市场的停牌股票断崖式地下降,目前每天停牌的股票不到 20 只,比例只有千分之五左右。这在全世界都是少有的。