Integrations

MkDocs

To integrate with MkDocs, you simply need to make sure rst-in-md is installed and then add the following to your mkdocs.yml file:

markdown_extensions:
  - attr_list
  - rst_in_md

PyMdown Extensions SuperFences

The SuperFences extension overrides the default code block behavior in Python Markdown. To make sure rst-in-md is properly called, you simply need to specify the extension pymdownx.superfences:

markdown_extensions:
  - attr_list
  - rst_in_md
  - pymdownx.superfences

You can read more about this integration in the explanation and reference.

Auto-Configuration

By installing both rst-in-md and pymdownx.superfences, you invoke an auto-configurator that will remove rst-in-md and add the proper custom_fences for pymdownx.superfences. It is equivalent to the following configuration:

markdown_extensions:
  - attr_list
- - rst_in_md
  - pymdownx.superfences:
+     custom_fences:
+       - name: rst
+         class: rst-in-md
+         format: !!python/name:rst_in_md.superfence_formatter
+        validate: !!python/name:rst_in_md.superfence_validator
+       - name: rest
+         class: rst-in-md
+         format: !!python/name:rst_in_md.superfence_formatter
+         validate: !!python/name:rst_in_md.superfence_validator
+       - name: restructuredtext
+         class: rst-in-md
+         format: !!python/name:rst_in_md.superfence_formatter
+         validate: !!python/name:rst_in_md.superfence_validator

If you want to customize the custom_fences, you can do so by simply not including rst-in-md in the markdown_extensions and specifying the custom_fences yourself.

The auto-configurator will work with other custom fences like mermaid.js as well, so only do this if you want to customize the rst-in-md superfences in particular.