CommonMark-py-Extensions

此包扩展了Python的commonmark CommonMark渲染库，增加了

• 基于GitHub Flavored Markdown的表格，以及对支持嵌入式块标记的多行单元格的进一步扩展。
• 一个新的渲染器将CommonMark转换为比原始CommonMark更美观的纯文本，以及一个将CommonMark再次转换为CommonMark的渲染器。

此库与commonmark内部紧密相连，并且仅与commonmark==0.8.0进行了测试。

注意：此项目是一个进行中的工作。它与GitHub Flavored Markdown兼容性很高，但在边缘情况和块结束规则上略有偏差。

安装

pip install commonmarkextensions

使用

表格

使用与上游库类似。要渲染表格

>>> import commonmark_extensions.tables
>>> commonmark_extensions.tables.commonmark("""
... | Header 1 | Header 2 |
... | -------- | -------- |
... | Cells    | **can**  |
... | `have`   | inlines. |
... """)
'<table>\n<thead>\n<tr>\n<th>Header 1</th>\n<th>Header 2</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Cells</td>\n<td><strong>can</strong></td>\n</tr>\n<tr>\n<td><code>have</code></td>\n<td>inlines.</td>\n</tr>\n</tbody>\n</table>\n'

列文本对齐使用:设置，如GitHub Flavored Markdown表格中所示。此示例将第一列设置为右对齐，第二列设置为居中对齐

| Sample | Header |
| -----: | :----: |
| A      | **bold** |
| C      | D      |

表格扩展还接受我们自己的多行单元格格式，其中单元格可以包含嵌入的块格式（例如单元格内的段落和列表）。在标题下方使用=代替-，然后使用=行分隔所有行（可选地，在表格末尾再使用一行=），如下所示：

markup = """
| Sample | Header |
| ====== | ====== |
| * A    | * B    |
| * C    | * D    |
| ====== | ====== |
| > C    | D      |
| ====== | ====== |
"""

生成的HTML是：

<table>
<thead>
<tr>
<th>Sample</th>
<th>Header</th>
</tr>
</thead>
<tbody>
<tr>
<td><ul>
<li>A</li>
<li>C</li>
</ul>
</td>
<td><ul>
<li>B</li>
<li>D</li>
</ul>
</td>
</tr>
<tr>
<td><blockquote>
<p>C</p>
</blockquote>
</td>
<td>D</td>
</tr>
</tbody>
</table>

纯文本

该库还包括用于纯文本和输出回CommonMark的新渲染器。这些渲染器大多数输入保持不变。例如，输入中的*斜体*在输出中渲染为*斜体*。但某些CommonMark格式（尤其是链接）对于非技术最终用户来说可能有些令人困惑。纯文本渲染器会修复并规范化标记

• 链接看起来比记法更友好。
• 缩进已规范化。
• 在CommonMark中指定标题有许多方法，因此输出中的标题样式已规范化。
• 实体引用如"Ӓ"被转换为Unicode字符。

请按以下方式使用纯文本渲染器：

>>> import commonmark_extensions.plaintext
>>> pt = commonmark_extensions.plaintext.commonmark("""
...   # Good morning!
... 
...   See [our website](https://www.govready.com) for details.
... """)
>>> print(pt)

这将生成：

Good morning!
#############

See our website <https://www.govready.com> for details.

CommonMark到CommonMark的渲染器只能通过实例化解析器和渲染器来使用——见下文。

限制

• 不支持html_inline和html_block节点，将引发RawHtmlNotAllowed异常。
• 图像被渲染为"[image]"加上它们的alt文本。

高级用法

您还可以单独实例化（如果需要，还可以子类化）解析器和渲染器

表格的高级用法

markup = """
| Sample | Header |
| -----: | :----: |
| A      | **bold** |
| C      | D      |
"""

from commonmark_extensions.tables import ParserWithTables, RendererWithTables
parser = ParserWithTables()
ast = parser.parse(markup)
print(RendererWithTables().render(ast))

这将输出：

<table>
<thead>
<tr>
<th align="right">Sample</th>
<th align="center">Header</th>
</tr>
</thead>
<tbody>
<tr>
<td align="right">A</td>
<td align="center"><strong>bold</strong></td>
</tr>
<tr>
<td align="right">C</td>
<td align="center">D</td>
</tr>
</tbody>
</table>

纯文本的高级用法

使用解析器和渲染器进行纯文本渲染

import commonmark
from commonmark_extensions.plaintext import PlainTextRenderer
parser = commonmark.Parser()
ast = parser.parse(markup)
print(PlainTextRenderer().render(ast))

还有一个用于生成CommonMark的渲染器，即规范化输入的CommonMark以生成更多CommonMark。

>>> markup = """
... # Good morning!
... 
... See [our website](https://www.govready.com) for details.
... """
>>> import commonmark
>>> from commonmark_extensions.plaintext import CommonMarkToCommonMarkRenderer
>>> parser = commonmark.Parser()
>>> ast = parser.parse(markup)
>>> print(CommonMarkToCommonMarkRenderer().render(ast))
Good morning\!
==============

See [our website](https://www.govready.com) for details.

CommonMarkToCommonMarkRenderer相当不错，但不完整。它还有一些额外的限制：它过于热情地转义标点符号，因为它无法确定何时可以不这样做；相邻的列表可能会合并，输出中不捕获列表的宽松/紧密区分。

测试

没有关于纯文本渲染器应生成什么的参考输出。但我已将所有CommonMark规范示例的输出保存到reference_output.txt中，以便随着该库的发展，我们可以看到变化。要检查与该库先前输出的一致性，请运行：

python3 commonmark_extensions/make_reference_output.py > reference_output.txt
git diff

通过回环CommonMark（解析，然后输出为CommonMark），然后解析该输出并将其输出为HTML来测试PlainTextRenderer。最终的HTML应与仅一步渲染到HTML的HTML匹配。

对于项目维护者

要发布到pypi的通用轮：

    pip3 install twine
    rm -rf dist
    python3 setup.py bdist_wheel --universal
    twine upload dist/*
    git tag v1.0.XXX
    git push --tags