1
1
# markdown-it-py
2
2
3
- [ ![ Github-DI ] [ github-ci ]] [ github-link ]
3
+ [ ![ Github-CI ] [ github-ci ]] [ github-link ]
4
4
[ ![ Coverage Status] [ codecov-badge ]] [ codecov-link ]
5
5
[ ![ PyPI] [ pypi-badge ]] [ pypi-link ]
6
6
[ ![ Conda] [ conda-badge ]] [ conda-link ]
7
7
[ ![ Code style: black] [ black-badge ]] [ black-link ]
8
8
9
- > Markdown parser done right. Fast and easy to extend.
9
+ > Markdown parser done right.
10
10
11
- - Follows the __ [ CommonMark spec] __ + adds syntax extensions & sugar (URL autolinking, typographer).
12
- - Configurable syntax! You can add new rules and even replace existing ones.
13
- - High speed .
14
- - [ Safe ] [ security-doc ] by default.
15
- - Pluginable
11
+ - Follows the __ [ CommonMark spec] ( http://spec.commonmark.org/ ) __ for baseline parsing
12
+ - Configurable syntax: you can add new rules and even replace existing ones.
13
+ - Pluggable: Adds syntax extensions to extend the parser (see the [ plugin list ] [ md-plugins ] ) .
14
+ - High speed (see our [ benchmarking tests ] [ md-performance ] )
15
+ - [ Safe by default ] [ md-security ]
16
16
17
-
18
- This is a Python port of [ markdown-it] ,
19
- and some of its associated plugins.
20
- It is still under development, so for now should be used with caution.
17
+ This is a Python port of [ markdown-it] , and some of its associated plugins.
18
+ For more details see: < https://markdown-it-py.readthedocs.io > .
21
19
22
20
For details on [ markdown-it] itself, see:
23
21
24
22
- The __ [ Live demo] ( https://markdown-it.github.io ) __
25
23
- [ The markdown-it README] [ markdown-it-readme ]
26
24
27
-
28
- __ Table of content__
29
-
30
- - [ markdown-it-py] ( #markdown-it-py )
31
- - [ The Port] ( #the-port )
32
- - [ Install] ( #install )
33
- - [ Basic usage] ( #basic-usage )
34
- - [ Benchmarking] ( #benchmarking )
35
- - [ Syntax extensions] ( #syntax-extensions )
36
- - [ Authors] ( #authors )
37
- - [ References / Thanks] ( #references--thanks )
38
- - [ Related Links] ( #related-links )
39
- - [ Other Ports] ( #other-ports )
40
-
41
-
42
- ## The Port
43
-
44
- Details of the port can be found in ` markdown_it/port.yaml ` and in ` port.yaml `
45
- within the extension folders. But the driving design philosophy has been to change as little of the
46
- fundamental code structure (file names, function name, etc) as possible, just sprinkling in a little Python syntactic sugar.
47
- It is very simple to write complimentary extensions for both language implementations!
48
-
49
-
50
- ## Install
25
+ ## Installation
51
26
52
27
``` bash
53
28
conda install -c conda-forge markdown-it-py
59
34
pip install markdown-it-py
60
35
```
61
36
62
-
63
37
## Basic usage
64
38
65
- See also:
66
-
67
- - [ Using ` markdown_it ` ] [ using-the-api ] - for an executable notebook guide to the API
68
- - [ Development info] - for plugins writers.
69
-
70
39
``` python
71
40
from markdown_it import MarkdownIt
72
41
from markdown_it.extensions.front_matter import front_matter_plugin
@@ -109,81 +78,14 @@ Type Ctrl-D to complete input, or Ctrl-C to exit.
109
78
</blockquote>
110
79
```
111
80
112
- ## Benchmarking
113
-
114
- markdown-it-py is the fastest _ ** CommonMark compliant** _ parser written in python!
115
-
116
- ``` console
117
- $ markdown-it-bench -n 30
118
- Test document: spec.md
119
- Test iterations: 30
120
- Running 7 test(s) ...
121
- =====================
122
- [mistune (0.8.4): 3.62 s]*
123
- markdown-it-py (0.1.0): 9.03 s
124
- mistletoe (0.10.0): 9.89 s
125
- commonmark-py (0.9.1): 20.82 s
126
- pymarkdown (3.2.1): 34.50 s
127
- pymarkdown:extra (3.2.1): 41.86 s
128
- panflute (1.12.5): 35.02 s
129
- ```
130
-
131
- As you can see, ` markdown-it-py ` doesn't pay with speed for it's flexibility.
132
-
133
- \* Note ` mistune ` is not CommonMark compliant, which is what allows for its
134
- faster parsing, at the expense of issues, for example, with nested inline parsing.
135
- See [ mistletoes's explanation] ( https://github.com/miyuchina/mistletoe#performance )
136
- for further details.
137
-
138
-
139
- ## Syntax extensions
140
-
141
- Embedded (enabled when using the ` "default" ` preset configuration):
142
-
143
- - [ Tables] ( https://help.github.com/articles/organizing-information-with-tables/ ) (GFM)
144
- - [ Strikethrough] ( https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text ) (GFM)
145
-
146
- * Via* plugins:
147
-
148
- A list of plugins that have/can be ported:
149
-
150
- - [ subscript] ( https://github.com/markdown-it/markdown-it-sub )
151
- - [ superscript] ( https://github.com/markdown-it/markdown-it-sup )
152
- - [ footnote] ( https://github.com/markdown-it/markdown-it-footnote )
153
- - [ definition list] ( https://github.com/markdown-it/markdown-it-deflist )
154
- - [ abbreviation] ( https://github.com/markdown-it/markdown-it-abbr )
155
- - [ emoji] ( https://github.com/markdown-it/markdown-it-emoji )
156
- - [ custom container] ( https://github.com/markdown-it/markdown-it-container )
157
- - [ insert] ( https://github.com/markdown-it/markdown-it-ins )
158
- - [ mark] ( https://github.com/markdown-it/markdown-it-mark )
159
- - ... and [ others] ( https://www.npmjs.org/browse/keyword/markdown-it-plugin )
160
-
161
-
162
- ## Authors
163
-
164
- - Chris Sewell [ github/chrisjsewell] ( https://github.com/chrisjsewell )
165
-
166
81
## References / Thanks
167
82
168
- Big thanks to the authors of [ markdown-it]
83
+ Big thanks to the authors of [ markdown-it] :
169
84
170
85
- Alex Kocharin [ github/rlidwka] ( https://github.com/rlidwka )
171
86
- Vitaly Puzrin [ github/puzrin] ( https://github.com/puzrin )
172
87
173
- Also [ John MacFarlane] ( https://github.com/jgm ) for his work on the
174
- CommonMark spec and reference implementations.
175
-
176
- ### Related Links
177
-
178
- - https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS,
179
- also contains latest spec & online demo.
180
- - http://talk.commonmark.org - CommonMark forum, good place to collaborate
181
- developers' efforts.
182
-
183
- ### Other Ports
184
-
185
- - [ motion-markdown-it] ( https://github.com/digitalmoksha/motion-markdown-it ) - Ruby/RubyMotion
186
-
88
+ Also [ John MacFarlane] ( https://github.com/jgm ) for his work on the CommonMark spec and reference implementations.
187
89
188
90
[ github-ci ] : https://github.com/ExecutableBookProject/markdown-it-py/workflows/Python%20package/badge.svg?branch=master
189
91
[ github-link ] : https://github.com/ExecutableBookProject/markdown-it-py
@@ -199,6 +101,6 @@ CommonMark spec and reference implementations.
199
101
[ CommonMark spec ] : http://spec.commonmark.org/
200
102
[ markdown-it ] : https://github.com/markdown-it/markdown-it
201
103
[ markdown-it-readme ] : https://github.com/markdown-it/markdown-it/blob/master/README.md
202
- [ security-doc ] : https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/security.md
203
- [ using-the-api ] : https://github.com/ExecutableBookProject/ markdown-it-py/tree/master/docs/using.md
204
- [ Development info ] : https://github.com/ExecutableBookProject/ markdown-it-py/tree/master/docs/development.md
104
+ [ md-security ] : https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/security.md
105
+ [ md-performance ] : https://markdown-it-py.readthedocs.io/en/latest/security.html
106
+ [ md-plugins ] : https://markdown-it-py.readthedocs.io/en/latest/plugins.html
0 commit comments