Implementation

Fenced Code Blocks

The general goal is to make it as easy as possible to make current Markdown files compatible with this tool. With that in mind, rst-in-md will convert all fenced code blocks with the rst language identifier to html as reStructuredText. This is a similar approach to how MkDocs-Material handles mermaid diagrams.

To make sure that the tool properly finds the code blocks, it has to run before the FencedBlockPreprocessor in the Python Markdown pipeline. This is done by setting the rst-in-md extension to be a higher priority than the fenced_code_block extension.

See general usage for examples.

Integration with PyMdown Extensions SuperFences

rst-in-md is designed to work with PyMdown Extensions SuperFences. The SuperFences extension is for the most part superior to the default fenced code block implementation. The SuperFences API allows for custom fences, like this one.

Usually, pymdownx.superfences require custom fences to be specified. However, rst-in-md automatically detects that pymdownx.superfences is installed and will properly handle the configuration for you. You can find that implemenation in the auto-configuration reference.

Stripped HTML Tags

Certain html tags generated by rst-in-md will be stripped out in order to attempt to provide loose parity to the Python Markdown output. This is done to prevent downstream code from breaking due to the differences in the output. For example, the class attribute is stripped because it can break the MkDocs-Material theme.

Inline Ignore

While using fenced code blocks is the least intrusive way to use rst-in-md, it may not always be the intended behavior to convert a particular code block. To prevent this, you can add a flag attribute to the code block you do not wish to convert.

This is only disables the conversion of the following code block, rather that the rest of the file, etc. The expectation is that if the user is using this tool, they want to convert the majority of the reStructuredText in their repository, so an opt-out mechanism is more appropriate.

See inline ignore for examples.

Graceful Failures

rst-in-md is designed to fail gracefully. If there is an error in the parsing of the reStructuredText, the tool will warn the user and fall back to standard Markdown rendering. This is used to prevent the tool from getting in the way of the user's workflow and is similar to how pymdown-extensions handles errors.