# 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](https://squidfunk.github.io/mkdocs-material/reference/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](https://github.com/Python-Markdown/markdown/blob/33359faa385f59b84cd87df5f4b0996055a482e2/markdown/extensions/fenced_code.py#L50) than the `fenced_code_block` extension.

See [general usage](../guides/general_usage.md) for examples.

## Integration with PyMdown Extensions SuperFences

`rst-in-md` is designed to work with [PyMdown Extensions SuperFences](https://facelessuser.github.io/pymdown-extensions/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](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#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](../reference/superfence.md#rst_in_md.RestructuredTextInMarkdownAutoConfigurator).

## Stripped HTML Tags

Certain html tags generated by `rst-in-md` will be stripped out in order to attempt to provide [loose parity](../explanations/limitations.md#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](https://squidfunk.github.io/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](../guides/inline_ignore.md) 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](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#exception-handling) handles errors.
