Docs and examples for all Markdown tags

[Hvass-Labs]

Context

The function get_all_rules() lists a large number of Markdown rules that can be enabled / disabled. But I can't seem to find a list of these in the docs. It would be very helpful if the docs give examples of the corresponding Markdown tags and what they look like when rendered to HTML.

I also wonder if some of these rules have options e.g. if the heading rule can enable/disable only some of the heading-types?

Thanks!

Proposal

No response

Tasks and updates

No response

[chrisjsewell]

Heya, well PRs to the documentation are always welcome 😄

It would probably go in https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser,

if the heading rule can enable/disable only some of the heading-types?

Not sure what you mean by types: heading refers to https://spec.commonmark.org/0.30/#atx-headings, and lheading refers to https://spec.commonmark.org/0.30/#setext-headings

[chrisjsewell]

Note, most of the rules behaviour are essentially "documented" via the fixture tests, e.g. for smartquotes https://github.com/executablebooks/markdown-it-py/blob/615eb3f36ceb05f316d1e7920249d45685f8f316/tests/test_port/fixtures/smartquotes.md (click on raw to see the expected HTML)

[Hvass-Labs]

I mean this as a friendly response, but it is perhaps not so realistic to expect outsiders to write your docs :-) We all have a lot of work to do, and it would take other people a disproportionate amount of time to understand your code in order to be able to document it properly. Instead allow me to elaborate on what I would find useful in your docs:

You already have a list in this section with the output from get_all_rules(), but not an explanation of what they do. It would be very helpful if you simply make a list of all these rules, their corresponding markdown tags, short examples, and links to the Markdown specs for a full explanation. Then it is much easier to enable / disable the Markdown rules we need.

I took a look at the file smartquotes.md you linked to, but I have no idea what that is :-)

Regarding heading "types" I mean levels.

Thanks!