‼️ BREAKING: Change `Token.attrs` to a dict (#144)

Instead of storing `attrs` as `[["key1", "value1"], ["key2", "value2"]]`,
use `{"key1": "value1", "key2": "value2"}`.

Upstream the list format is only used to guarantee order: https://github.com/markdown-it/markdown-it/issues/142,
but in Python 3.7+ dictionary order is now guaranteed by the specification
(in Python 3.6 it is also preserved as an implementation detail).
This change improves typing and performance.

One should anyhow generally use the `attrGet`, `attrSet`, `attrPush` and `attrJoin` methods
to manipulate `Token.attrs`, which all have an identical signature to those upstream.

To minimize how breaking this change is,
auto-conversion is done on `Token` initiation,
i.e. you can still use `Token("type", "tag", 0, attrs=[["key", "value"]])`,
and also `Token.as_dict(as_upstream=True)` converts the dict back to `null`/`list`, 
o that they can still be directly compared to those produced in the `debug` tab of https://markdown-it.github.io/.

The `meta_serializer` option has also been added to `Token.as_dict`,
which now ensures that this method is always able to produce valid JSON.
18 files changed
tree: b078245aea62b7e8734ff395f570485140f60253
  1. .flake8
  2. .github/
  3. .gitignore
  4. .mypy.ini
  5. .pre-commit-config.yaml
  6. .readthedocs.yml
  9. LICENSE.markdown-it
  10. MANIFEST.in
  11. README.md
  12. benchmarking/
  13. codecov.yml
  14. docs/
  15. docstring.fmt.mustache
  16. markdown_it/
  17. setup.py
  18. tests/
  19. tox.ini


Github-CI Coverage Status PyPI Conda Code style: black PyPI - Downloads

Markdown parser done right.

This is a Python port of markdown-it, and some of its associated plugins. For more details see: https://markdown-it-py.readthedocs.io.

For details on markdown-it itself, see:


conda install -c conda-forge markdown-it-py


pip install markdown-it-py


Python API Usage

Render markdown to HTML with markdown-it-py and a custom configuration with and without plugins and features:

from markdown_it import MarkdownIt
from markdown_it.extensions.front_matter import front_matter_plugin
from markdown_it.extensions.footnote import footnote_plugin

md = (
text = ("""
a: 1

a | b
- | -
1 | 2

A footnote [^1]

[^1]: some details
tokens = md.parse(text)
html_text = md.render(text)

Command-line Usage

Render markdown to HTML with markdown-it-py from the command-line:

usage: markdown-it [-h] [-v] [filenames [filenames ...]]

Parse one or more markdown files, convert each to HTML, and print to stdout

positional arguments:
  filenames      specify an optional list of files to convert

optional arguments:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit


  $ markdown-it
  markdown-it-py [version 0.0.0] (interactive)
  Type Ctrl-D to complete input, or Ctrl-C to exit.
  >>> # Example
  ... > markdown *input*
  <p>markdown <em>input</em></p>


  $ markdown-it README.md README.footer.md > index.html

References / Thanks

Big thanks to the authors of markdown-it:

Also John MacFarlane for his work on the CommonMark spec and reference implementations.