markdown-it-py 使用教程

项目介绍

markdown-it-py 是一个遵循 CommonMark 规范的 Markdown 解析器，具有高度的可配置性和扩展性。它是 markdown-it 的 Python 版本，支持插件扩展和高速解析。该项目是 Google's Assured Open Source Software 的成员之一。

项目快速启动

安装

你可以通过 pip 或 conda 安装 markdown-it-py：

pip install markdown-it-py

或

conda install -c conda-forge markdown-it-py

基本使用

以下是一个简单的示例，展示如何使用 markdown-it-py 将 Markdown 文本转换为 HTML：

from markdown_it import MarkdownIt

md = MarkdownIt()
text = "# Hello, world!\n\nThis is a **markdown** example."
html_text = md.render(text)
print(html_text)

使用插件

markdown-it-py 支持通过插件扩展功能。以下是一个使用 front_matter 和 footnote 插件的示例：

from markdown_it import MarkdownIt
from mdit_py_plugins.front_matter import front_matter_plugin
from mdit_py_plugins.footnote import footnote_plugin

md = (
    MarkdownIt('commonmark', {'breaks': True, 'html': True})
    .use(front_matter_plugin)
    .use(footnote_plugin)
    .enable('table')
)

text = """
---
a: 1
---
a | b
- | -
1 | 2

A footnote [^1]

[^1]: some details
"""

tokens = md.parse(text)
html_text = md.render(text)
print(html_text)

应用案例和最佳实践

生成静态网站

markdown-it-py 可以与静态网站生成器结合使用，将 Markdown 文件转换为 HTML 页面。以下是一个简单的示例：

from markdown_it import MarkdownIt
from pathlib import Path

md = MarkdownIt()
text = Path("README.md").read_text()
html_text = md.render(text)
Path("output.html").write_text(html_text)

集成到 Web 应用

在 Web 应用中，可以使用 markdown-it-py 实时解析用户输入的 Markdown 文本并显示为 HTML。以下是一个 Flask 应用的示例：

from flask import Flask, request, render_template_string
from markdown_it import MarkdownIt

app = Flask(__name__)
md = MarkdownIt()

@app.route('/', methods=['GET', 'POST'])
def index():
    if request.method == 'POST':
        markdown_text = request.form['markdown']
        html_text = md.render(markdown_text)
        return render_template_string(f"<div>{html_text}</div>")
    return '''
        <form method="post">
            <textarea name="markdown"></textarea>
            <input type="submit">
        </form>
    '''

if __name__ == '__main__':
    app.run(debug=True)

典型生态项目

mdit-py-plugins

mdit-py-plugins 是一个包含多个插件的库，可以扩展 markdown-it-py 的功能，例如 front_matter、footnote 等。

linkify-it-py

linkify-it-py 是一个用于检测和转换链接的库，可以与 markdown-it-py 结合使用，自动识别文本中的链接并转换为 HTML 链接。

markdown-it-pyrs

markdown-it-pyrs 是一个实验性的 Rust 绑定，旨在提供更快的解析速度。

通过这些生态项目，markdown-it-py 可以满足各种复杂的 Markdown 解析需求，并提供高性能的解析体验。