表和CommonMark的纯文本呈现扩展。
commonmarkextensions的Python项目详细描述
Commonmark PY扩展
这个包扩展了python的commonmarkcommonmark呈现库:
- GitHub Flavored Markdown中的表,对支持 嵌入块标记。
- 一个新的渲染器将commonmark转换为比原来的commonmark更漂亮的纯文本,一个渲染器将commonmark再次转换为commonmark。
这个库与commonmark内部紧密链接,并且只使用commonmark==0.8.0
进行了测试。
注:本项目正在进行中。它与github风格的降价非常兼容,但在边缘情况和块结束规则上有点偏差。
安装
pip install commonmarkextensions
用法
表格
用法与上游库类似。渲染表格:
>>>importcommonmark_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风格的标记表,使用:
设置列文本对齐。此示例将第一列设置为右对齐,第二列设置为居中对齐:
| Sample | Header | | -----: | :----: | | A | **bold** | | C | D |
tables扩展还接受我们自己的多行单元格格式,其中的单元格可以保存嵌入的块格式(例如段落
以及单元格中的列表)。使用=
而不是头下的-
,然后用=
行分隔所有行(可选地用另一行=
结束表),如:
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的新渲染器。大部分
这些渲染器保持输入不变。例如,输入中的*Italic*
在
输出。但一些通用标记格式(尤其是链接)让非技术性最终用户感到困惑。
纯文本呈现程序修复并规范化标记:
- 链接看起来比符号更友好。
- 缩进是标准化的。
- 有很多方法可以在commonmark中指定标题,因此标题样式在输出中是规范化的。
- 像“_”这样的实体引用被转换为Unicode字符。
按如下方式使用纯文本呈现程序:
>>>importcommonmark_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异常。
- 图像将呈现为“[图像]”及其alt文本。
高级用法
您还可以分别实例化(和子类,如果您愿意的话)解析器和呈现器:
表的高级用法
markup="""| Sample | Header || -----: | :----: || A | **bold** || C | D |"""fromcommonmark_extensions.tablesimportParserWithTables,RendererWithTablesparser=ParserWithTables()ast=parser.parse(markup)print(RendererWithTables().render(ast))
输出:
<table><thead><tr><thalign="right">Sample</th><thalign="center">Header</th></tr></thead><tbody><tr><tdalign="right">A</td><tdalign="center"><strong>bold</strong></td></tr><tr><tdalign="right">C</td><tdalign="center">D</td></tr></tbody></table>
纯文本的高级用法
使用解析器和呈现器进行纯文本呈现:
importcommonmarkfromcommonmark_extensions.plaintextimportPlainTextRendererparser=commonmark.Parser()ast=parser.parse(markup)print(PlainTextRenderer().render(ast))
有第二个渲染器用于生成commonmark,即规范化输入commonmark 变得更普通。
>>>markup="""... # Good morning!... ... See [our website](https://www.govready.com) for details.... """>>>importcommonmark>>>fromcommonmark_extensions.plaintextimportCommonMarkToCommonMarkRenderer>>>parser=commonmark.Parser()>>>ast=parser.parse(markup)>>>print(CommonMarkToCommonMarkRenderer().render(ast))Goodmorning\!==============See[ourwebsite](https://www.govready.com)fordetails.
CommonMarkToCommonMarkRenderer相当不错,但还不完整。它还有一些额外的限制:它过分热衷于反斜杠转义标点字符,因为它无法判断何时不这样做是安全的,相邻的列表可能会组合在一起,列表的松散/紧密区别不会在输出中捕获。
测试
对于纯文本呈现程序应该生成的内容没有引用输出。但是我已经将所有commonmark规范示例的输出保存到reference_output.txt
中,这样随着这个库的发展,我们可以看到变化。要检查与此库以前的输出是否一致,请运行::
python3 commonmark_extensions/make_reference_output.py > reference_output.txt
git diff
PlainTextRenderer通过往返CommonMark(解析,然后输出为CommonMark)进行测试,然后解析并输出到HTML。最终的html应该与您在一个步骤中从呈现到html得到的html相匹配。
对于项目维护人员
将通用控制盘发布到pypi::
^{公关13}$