Contribute to markdown-it-py¶
We welcome all contributions! ✨
See the EBP Contributing Guide for general details, and below for guidance specific to markdown-it-py.
Before continuing, make sure you’ve read:
Details of the port can be found in the
markdown_it/port.yaml and in
port.yaml files, within the extension folders.
markdown-it-py[code_style] makes the pre-commit package available, which will ensure this style is met before commits are submitted, by reformatting the code and testing for lint errors.
It can be setup by:
>> cd markdown-it-py >> pre-commit install
Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
All functions and class methods should be annotated with types and include a docstring.
The prefered docstring format is outlined in
markdown-it-py/docstring.fmt.mustache and can be used automatically with the autodocstring VS Code extension.
For code tests, markdown-it-py uses pytest):
>> cd markdown-it-py >> pytest
You can also use tox, to run the tests in multiple isolated environments (see the
tox.ini file for available test environments):
>> cd markdown-it-py >> tox -p
This can also be used to run benchmarking tests using pytest-benchmark:
>> cd markdown-it-py tox -e py38-bench-packages -- --benchmark-min-rounds 50
For documentation build tests:
>> cd markdown-it-py/docs >> make clean >> make html-strict
Contributing a plugin¶
Try to find the right place for your plugin rule:
Will it conflict with existing markup (by priority)?
If yes - you need to write an inline or block rule.
If no - you can morph tokens within core chains.
Remember that token morphing in core chains is always more simple than writing block or inline rules, if you don’t copy existing ones. However, block and inline rules are usually faster.
Sometimes, it’s enough to only modify the renderer, for example, to add header IDs or
target="_blank"for the links.
I need async rule, how to do it?¶
Sorry. You can’t do it directly. All complex parsers are sync by nature. But you can use workarounds:
On parse phase, replace content by random number and store it in
Do async processing over collected data.
Render content and replace those random numbers with text; or replace first, then render.
Alternatively, you can render HTML, then parse it to DOM, or cheerio AST, and apply transformations in a more convenient way.
Why is my inline rule not executed?¶
The inline parser skips pieces of texts to optimize speed. It stops only on a small set of chars, which can be tokens. We did not made this list extensible for performance reasons too.
If you are absolutely sure that something important is missing there - create a ticket and we will consider adding it as a new charcode.