📚 Update docs

README.md

@@ -24,6 +24,9 @@ For details on [markdown-it] itself, see:
 - The __[Live demo](https://markdown-it.github.io)__
 - [The markdown-it README][markdown-it-readme]
 
+**See also:** [markdown-it-pyrs](https://github.com/chrisjsewell/markdown-it-pyrs) for an experimental Rust binding,
+for even more speed!
+
 ## Installation
 
 ```bash
@@ -143,6 +146,6 @@ Also [John MacFarlane](https://github.com/jgm) for his work on the CommonMark sp
 [CommonMark spec]: http://spec.commonmark.org/
 [markdown-it]: https://github.com/markdown-it/markdown-it
 [markdown-it-readme]: https://github.com/markdown-it/markdown-it/blob/master/README.md
-[md-security]: https://markdown-it-py.readthedocs.io/en/latest/other.html
-[md-performance]: https://markdown-it-py.readthedocs.io/en/latest/other.html
+[md-security]: https://markdown-it-py.readthedocs.io/en/latest/security.html
+[md-performance]: https://markdown-it-py.readthedocs.io/en/latest/performance.html
 [md-plugins]: https://markdown-it-py.readthedocs.io/en/latest/plugins.html

benchmarking/bench_packages.py

@@ -18,6 +18,15 @@ def test_markdown_it_py(benchmark, spec_text):
  benchmark(parser.render, spec_text)
 
 
+@pytest.mark.benchmark(group="packages")
+def test_markdown_it_pyrs(benchmark, spec_text):
+ import markdown_it_pyrs
+
+ parser = markdown_it_pyrs.MarkdownIt("commonmark")
+ benchmark.extra_info["version"] = markdown_it_pyrs.__version__
+ benchmark(parser.render, spec_text)
+
+
 @pytest.mark.benchmark(group="packages")
 def test_mistune(benchmark, spec_text):
  import mistune

docs/architecture.md

@@ -1,6 +1,6 @@
 (md/architecture)=
 
-# markdown-it design principles
+# Design principles
 
 (md/data-flow)=
 ## Data flow

docs/conf.py

@@ -64,8 +64,11 @@
 # a list of builtin themes.
 #
 html_title = "markdown-it-py"
+html_logo = html_favicon = "_static/markdown-it-py.svg"
 html_theme = "sphinx_book_theme"
 html_theme_options = {
+ "home_page_in_toc": True,
+ "use_repository_button": True,
  "use_edit_page_button": True,
  "repository_url": "https://github.com/executablebooks/markdown-it-py",
  "repository_branch": "master",

docs/contributing.md

@@ -1,4 +1,4 @@
-# Contribute to markdown-it-py
+# Contribute
 
 We welcome all contributions! ✨
 

docs/index.md

@@ -33,7 +33,8 @@ Also [John MacFarlane](https://github.com/jgm) for his work on the CommonMark sp
 
 using
 architecture
-other
+security
+performance
 plugins
 contributing
 api/markdown_it

docs/performance.md

@@ -0,0 +1,28 @@
+(md/performance)=
+
+# Performance
+
+You can view our continuous integration benchmarking analysis at: <https://executablebooks.github.io/markdown-it-py/dev/bench/>,
+or you can run it for yourself within the repository:
+
+```bash
+tox -e py311-bench-packages -- --benchmark-columns mean,stddev
+```
+
+| package | version | mean (ms) | stddev |
+| -------------------- | ------- | --------- | ------- |
+| markdown-it-pyrs[^1] | 0.2.1 | 6.410 | 0.426 |
+| mistune[^2] | 3.0.1 | 80.409 | 2.335 |
+| **markdown-it-py** | 3.0.0 | 97.242 | 4.427 |
+| mistletoe | 1.1.0 | 99.633 | 4.628 |
+| commonmark-py | 0.9.1 | 300.403 | 9.706 |
+| pymarkdown | 3.4.3 | 387.775 | 10.394 |
+| pymarkdown (+extras) | 3.4.3 | 646.564 | 11.316 |
+| panflute | 2.3.0 | 860.105 | 208.607 |
+
+As you can see, `markdown-it-py` doesn't pay with speed for it's flexibility.
+
+[^1]: `markdown-it-pyrs` is a Rust implementation of `markdown-it-py`'s parser, in beta development, check it out at: <https://github.com/chrisjsewell/markdown-it-pyrs>
+[^2]: `mistune` is not CommonMark compliant, which is what allows for its
+faster parsing, at the expense of issues, for example, with nested inline parsing.
+See [mistletoes's explanation](https://github.com/miyuchina/mistletoe/blob/master/performance.md) for further details.

docs/other.md → docs/security.md

@@ -33,34 +33,3 @@ If those depend on user input - always add prefixes to avoid DOM clobbering.
 See [discussion](https://github.com/markdown-it/markdown-it/issues/28) for details.
 
 So, if you decide to use plugins that add extended class syntax or autogenerating header anchors - be careful.
-
-(md/performance)=
-
-# Performance
-
-You can view our continuous integration benchmarking analysis at: <https://executablebooks.github.io/markdown-it-py/dev/bench/>,
-or you can run it for yourself within the repository:
-
-```console
-$ tox -e py38-bench-packages -- --benchmark-columns mean,stddev
-
-Name (time in ms) Mean StdDev
----------------------------------------------------------------
-test_mistune 70.3272 (1.0) 0.7978 (1.0)
-test_mistletoe 116.0919 (1.65) 6.2870 (7.88)
-test_markdown_it_py 152.9022 (2.17) 4.2988 (5.39)
-test_commonmark_py 326.9506 (4.65) 15.8084 (19.81)
-test_pymarkdown 368.2712 (5.24) 7.5906 (9.51)
-test_pymarkdown_extra 640.4913 (9.11) 15.1769 (19.02)
-test_panflute 678.3547 (9.65) 9.4622 (11.86)
----------------------------------------------------------------
-```
-
-As you can see, `markdown-it-py` doesn't pay with speed for it's flexibility.
-
-```{note}
-`mistune` is not CommonMark compliant, which is what allows for its
-faster parsing, at the expense of issues, for example, with nested inline parsing.
-See [mistletoes's explanation](https://github.com/miyuchina/mistletoe/blob/master/performance.md)
-for further details.
-```

pyproject.toml

@@ -39,13 +39,14 @@ compare = [
  "commonmark~=0.9",
  "markdown~=3.4",
  "mistletoe~=1.0",
- "mistune~=2.0",
+ "mistune~=3.0",
  "panflute~=2.3",
+ "markdown-it-pyrs",
 ]
 linkify = ["linkify-it-py>=1,<3"]
 plugins = ["mdit-py-plugins"]
 rtd = [
- "mdit-py-plugins @ git+https://github.com/executablebooks/mdit-py-plugins@master",
+ "mdit-py-plugins",
  "myst-parser",
  "pyyaml",
  "sphinx",