.\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "COMMONMARK-PY" "1" "May 30, 2026" "0.9.2" "commonmark.py" .SH NAME commonmark-py \- commonmark.py Documentation .sp [image: No Maintenance Intended] [image] \% .sp \fBWarning:\fP commonmark.py is now deprecated. We recommend using markdown\-it\-py \% for a commonmark parser going forward. See this issue \% for background and discussion. .sp \-\- .sp commonmark.py is a pure Python port of jgm \%\(aqs commonmark.js \%, a Markdown parser and renderer for the CommonMark \% specification, using only native modules. Once both this project and the CommonMark specification are stable we will release the first \fB1.0\fP version and attempt to keep up to date with changes in \fBcommonmark.js\fP\&. .sp commonmark.py is tested against the CommonMark spec with Python versions 2.7, 3.5, 3.6, 3.7, and 3.8. .sp \fBCurrent version:\fP 0.9.2 .sp [image: Pypi Link] [image] \% [image: Build Status] [image] \% [image: Documentation Status] [image] \% .SH INSTALLATION .INDENT 0.0 .INDENT 3.5 .sp .EX $ pip install commonmark .EE .UNINDENT .UNINDENT .SH USAGE .INDENT 0.0 .INDENT 3.5 .sp .EX >>> import commonmark >>> commonmark.commonmark(\(aq*hello!*\(aq) \(aq

hello!

\en\(aq .EE .UNINDENT .UNINDENT .sp Or, without the syntactic sugar: .INDENT 0.0 .INDENT 3.5 .sp .EX import commonmark parser = commonmark.Parser() ast = parser.parse(\(dqHello *World*\(dq) renderer = commonmark.HtmlRenderer() html = renderer.render(ast) print(html) #

Hello World

# inspecting the abstract syntax tree json = commonmark.dumpJSON(ast) commonmark.dumpAST(ast) # pretty print generated AST structure .EE .UNINDENT .UNINDENT .sp There is also a CLI: .INDENT 0.0 .INDENT 3.5 .sp .EX $ cmark README.md \-o README.html $ cmark README.md \-o README.json \-aj # output AST as JSON $ cmark README.md \-a # pretty print generated AST structure $ cmark \-h usage: cmark [\-h] [\-o [O]] [\-a] [\-aj] [infile] Process Markdown according to the CommonMark specification. positional arguments: infile Input Markdown file to parse, defaults to stdin optional arguments: \-h, \-\-help show this help message and exit \-o [O] Output HTML/JSON file, defaults to stdout \-a Print formatted AST \-aj Output JSON AST .EE .UNINDENT .UNINDENT .SH CONTRIBUTING .sp If you would like to offer suggestions/optimizations/bugfixes through pull requests please do! Also if you find an error in the parser/renderer that isn\(aqt caught by the current test suite please open a new issue and I would also suggest you send the commonmark.js \% project a pull request adding your test to the existing test suite. .SH TESTS .sp To work on commonmark.py, you will need to be able to run the test suite to make sure your changes don\(aqt break anything. To run the tests, you can do something like this: .INDENT 0.0 .INDENT 3.5 .sp .EX $ pyvenv venv $ ./venv/bin/python setup.py develop test .EE .UNINDENT .UNINDENT .sp The tests script, \fBcommonmark/tests/run_spec_tests.py\fP, is pretty much a devtool. As well as running all the tests embedded in \fBspec.txt\fP it also allows you to run specific tests using the \fB\-t\fP argument, provide information about passed tests with \fB\-p\fP, percentage passed by category of test with \fB\-s\fP, and enter markdown interactively with \fB\-i\fP (In interactive mode end a block by inputting a line with just \fBend\fP, to quit do the same but with \fBquit\fP). \fB\-d\fP can be used to print call tracing. .INDENT 0.0 .INDENT 3.5 .sp .EX $ ./venv/bin/python commonmark/tests/run_spec_tests.py \-h usage: run_spec_tests.py [\-h] [\-t T] [\-p] [\-f] [\-i] [\-d] [\-np] [\-s] script to run the CommonMark specification tests against the commonmark.py parser. optional arguments: \-h, \-\-help show this help message and exit \-t T Single test to run or comma separated list of tests (\-t 10 or \-t 10,11,12,13) \-p Print passed test information \-f Print failed tests (during \-np...) \-i Interactive Markdown input mode \-d Debug, trace calls \-np Only print section header, tick, or cross \-s Print percent of tests passed by category .EE .UNINDENT .UNINDENT .SH AUTHORS .INDENT 0.0 .IP \(bu 2 Bibek Kafle \% .IP \(bu 2 Roland Shoemaker \% .UNINDENT .SS API .SS HTML .INDENT 0.0 .TP .B class commonmark.render.html.HtmlRenderer(options={}) .INDENT 7.0 .TP .B out(s) Concatenate a string to the buffer possibly escaping the content. .sp Concrete renderer implementations should override this method. .sp @param str {String} The string to concatenate. .UNINDENT .INDENT 7.0 .TP .B tag(name, attrs=None, selfclosing=None) Helper function to produce an HTML tag. .UNINDENT .UNINDENT .SS reStructuredText .INDENT 0.0 .TP .B class commonmark.render.rst.ReStructuredTextRenderer(indent_char=\(aq \(aq) Render reStructuredText from Markdown .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX import commonmark parser = commonmark.Parser() ast = parser.parse(\(aqHello \(gainline code\(ga example\(aq) renderer = commonmark.ReStructuredTextRenderer() rst = renderer.render(ast) print(rst) # Hello \(ga\(gainline code\(ga\(ga example .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B lit(s) Concatenate a literal string to the buffer. .sp @param str {String} The string to concatenate. .UNINDENT .UNINDENT .SS Parser .INDENT 0.0 .TP .B class commonmark.blocks.Parser(options={}) .INDENT 7.0 .TP .B add_child(tag, offset) Add block of type tag as a child of the tip. If the tip can\(aqt accept children, close and finalize it and try its parent, and so on til we find a block that can accept children. .UNINDENT .INDENT 7.0 .TP .B add_line() Add a line to the block at the tip. We assume the tip can accept lines \-\- that check should be done before calling this. .UNINDENT .INDENT 7.0 .TP .B close_unmatched_blocks() Finalize and close any unmatched blocks. .UNINDENT .INDENT 7.0 .TP .B finalize(block, line_number) Finalize a block. Close it and do any necessary postprocessing, e.g. creating string_content from strings, setting the \(aqtight\(aq or \(aqloose\(aq status of a list, and parsing the beginnings of paragraphs for reference definitions. Reset the tip to the parent of the closed block. .UNINDENT .INDENT 7.0 .TP .B incorporate_line(ln) Analyze a line of text and update the document appropriately. .sp We parse markdown text by calling this on each line of input, then finalizing the document. .UNINDENT .INDENT 7.0 .TP .B parse(my_input) The main parsing function. Returns a parsed document AST. .UNINDENT .INDENT 7.0 .TP .B process_inlines(block) Walk through a block & children recursively, parsing string content into inline content where appropriate. .UNINDENT .UNINDENT .SS Node .INDENT 0.0 .TP .B class commonmark.node.NodeWalker(root) .INDENT 7.0 .TP .B nxt() for backwards compatibility .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class commonmark.node.Node(node_type, sourcepos) .UNINDENT .SH Author Roland Shoemaker, Bibek Kafle .SH Copyright 2014-2019, Roland Shoemaker, Bibek Kafle .\" End of generated man page.