📚 Update docs (#292)

Author: chrisjsewell

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/_static/markdown-it-py.svg

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

docs/architecture.md

@@ -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/conf.py

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

docs/contributing.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/index.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/performance.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.
-```

docs/other.md renamed to docs/security.md

@@ -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",