Skip to content

Commit 5e536c5

Browse files
committed
📚 DOCS: Update and improve
1 parent 008e70f commit 5e536c5

14 files changed

+270
-311
lines changed

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,6 @@ apidoc/
137137
__pycache__/
138138
.ropeproject/
139139
*.egg-info/
140-
vscode/
140+
.vscode/
141141

142142
docs/api/

.readthedocs.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,7 @@ python:
77
path: .
88
extra_requirements:
99
- rtd
10+
11+
sphinx:
12+
builder: html
13+
fail_on_warning: true

.vscode/settings.json

Lines changed: 0 additions & 17 deletions
This file was deleted.

CONTRIBUTING.md

Lines changed: 0 additions & 76 deletions
This file was deleted.

README.md

Lines changed: 15 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,28 @@
11
# markdown-it-py
22

3-
[![Github-DI][github-ci]][github-link]
3+
[![Github-CI][github-ci]][github-link]
44
[![Coverage Status][codecov-badge]][codecov-link]
55
[![PyPI][pypi-badge]][pypi-link]
66
[![Conda][conda-badge]][conda-link]
77
[![Code style: black][black-badge]][black-link]
88

9-
> Markdown parser done right. Fast and easy to extend.
9+
> Markdown parser done right.
1010
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]
1616

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>.
2119

2220
For details on [markdown-it] itself, see:
2321

2422
- The __[Live demo](https://markdown-it.github.io)__
2523
- [The markdown-it README][markdown-it-readme]
2624

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
5126

5227
```bash
5328
conda install -c conda-forge markdown-it-py
@@ -59,14 +34,8 @@ or
5934
pip install markdown-it-py
6035
```
6136

62-
6337
## Basic usage
6438

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-
7039
```python
7140
from markdown_it import MarkdownIt
7241
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.
10978
</blockquote>
11079
```
11180

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-
16681
## References / Thanks
16782

168-
Big thanks to the authors of [markdown-it]
83+
Big thanks to the authors of [markdown-it]:
16984

17085
- Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
17186
- Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
17287

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.
18789

18890
[github-ci]: https://github.com/ExecutableBookProject/markdown-it-py/workflows/Python%20package/badge.svg?branch=master
18991
[github-link]: https://github.com/ExecutableBookProject/markdown-it-py
@@ -199,6 +101,6 @@ CommonMark spec and reference implementations.
199101
[CommonMark spec]: http://spec.commonmark.org/
200102
[markdown-it]: https://github.com/markdown-it/markdown-it
201103
[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

docs/Makefile

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,11 @@ help:
1818
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1919
%: Makefile
2020
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+
22+
# raise warnings to errors
23+
html-strict:
24+
@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
25+
26+
# increase logging level to verbose
27+
html-verbose:
28+
@$(SPHINXBUILD) -b html -v "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)

docs/architecture.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
# markdown-it design principles
1+
(md/architecture)=
22

3+
# markdown-it design principles
34

45
## Data flow
56

docs/conf.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
"sphinx.ext.intersphinx",
3434
"myst_nb",
3535
"sphinx_copybutton",
36+
"sphinx_panels",
3637
]
3738

3839
# Add any paths that contain templates here, relative to this directory.
@@ -57,6 +58,7 @@
5758
"repository_branch": "master",
5859
"path_to_docs": "docs",
5960
}
61+
panels_add_boostrap_css = False
6062

6163
# Add any paths that contain custom static files (such as style sheets) here,
6264
# relative to this directory. They are copied after the builtin static files,

0 commit comments

Comments
 (0)