1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
|
CommonMark-py
=============
Pure Python port of `jgm <https://github.com/jgm>`__'s
`stmd.js <https://github.com/jgm/stmd/blob/master/js/stmd.js>`__, a
Markdown parser and renderer for the
`CommonMark <http://commonmark.org>`__ specification, using only native
modules. Once both this project and the CommonMark specification are
stable we will release the first ``1.0`` version and attempt to keep up
to date with changes in ``stmd.js``.
We are currently at the same development stage (actually a bit ahead
because we have implemented HTML entity conversion and href URL
escaping) as ``stmd.js``. Since Python versions pre-3.4 use outdated
(i.e. not HTML5 spec) entity conversion, I've converted the 3.4
implementation into a single file, ``entitytrans.py`` which so far seems
to work (all tests pass on 2.7, 3.3, and 3.4).
**Current version:** 0.5.4
|Build Status|
Installation
------------
::
rolands@kamaji:~$ pip install commonmark
Usage
-----
::
import CommonMark
parser = CommonMark.DocParser()
renderer = CommonMark.HTMLRenderer()
ast = parser.parse("Hello *World*")
html = renderer.render(ast)
json = CommonMark.ASTtoJSON(ast)
CommonMark.dumpAST(ast) # pretty print generated AST structure
print(html) # <p>Hello <em>World</em><p/>
----- or -----
rolands@kamaji:~$ cmark.py README.md -o README.html
rolands@kamaji:~$ cmark.py README.md -o README.json -aj # output AST as JSON
rolands@kamaji:~$ cmark.py README.md -a # pretty print generated AST structure
rolands@kamaji:~$ cmark.py -h
usage: cmark.py [-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
Contributing
------------
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't caught by the current test suite please open
a new issue and I would also suggest you send the
`stmd.js <https://github.com/jgm/stmd/blob/master/js/stmd.js>`__ project
a pull request adding your test to the existing test suite.
Tests
-----
The tests script, ``CommonMark-tests.py``, is pretty much a devtool. As
well as running all the tests embeded in ``spec.txt`` it also allows you
to run specific tests using the ``-t`` argument, provide information
about passed tests with ``-p``, percentage passed by category of test
with ``-s``, and enter markdown interactively with ``-i`` (In
interactive mode end a block by inputing a line with just ``end``, to
quit do the same but with ``quit``). ``-d`` can be used to print call
tracing.
::
rolands@kamaji:~/utils/CommonMark-py$ python CommonMark-tests.py -h
usage: CommonMark-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 seperated 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
Authors
-------
- `Bibek Kafle <https://github.com/kafle>`__
- `Roland Shoemaker <https://github.com/rolandshoemaker>`__
.. |Build Status| image:: https://travis-ci.org/rolandshoemaker/CommonMark-py.svg?branch=master
:target: https://travis-ci.org/rolandshoemaker/CommonMark-py
|