mdit_details.py
The markata.plugins.mdit_details
plugin adds support for collapsible details/summary
sections in markdown using the ???
syntax. This is similar to HTML's <details>
element
but with a more markdown-friendly syntax.
Installation
This plugin is built-in and enabled by default through the 'default' plugin. If you want to be explicit, you can add it to your list of plugins:
hooks = [ "markata.plugins.mdit_details", ]
Uninstallation
Since this plugin is included in the default plugin set, to disable it you must explicitly add it to the disabled_hooks list if you are using the 'default' plugin:
disabled_hooks = [ "markata.plugins.mdit_details", ]
Configuration
This plugin requires no explicit configuration. It automatically processes details blocks in your markdown content.
Functionality
Basic Usage
Create collapsible sections:
??? note "Optional Title" This content will be collapsible. It can contain *any* markdown. ???+ note "Open by Default" The + symbol makes this section expanded by default.
Supported Styles
Default styles include:
- note
- info
- warning
- danger
- success
- question
- abstract
- example
Syntax Options
The plugin supports:
- Basic:
??? type
- With title:
??? type "Custom Title"
- Open by default:
???+ type
- No title: Title defaults to capitalized type
HTML Output
Generated HTML structure:
<details class="details type"> <summary>Title Text</summary> <div class="details-content"> <!-- Markdown content --> </div> </details>
Nesting Support
Details blocks can be nested:
??? outer "Outer Section" Some content ??? inner "Inner Section" Nested content
Dependencies
This plugin depends on:
- markdown-it-py for markdown parsing
- The
render_markdown
plugin for final HTML output
Function
details_plugin function
Plugin to use
python-markdown style detailss <https://python-markdown.github.io/extensions/details>
_.
.. code-block:: md
??? note
*content*
Note, this is ported from
markdown-it-admon <https://github.com/commenthol/markdown-it-admon>
_.
details_plugin source
def details_plugin(md: MarkdownIt, render: Optional[Callable] = None) -> None: """Plugin to use `python-markdown style detailss <https://python-markdown.github.io/extensions/details>`_. .. code-block:: md ??? note *content* Note, this is ported from `markdown-it-admon <https://github.com/commenthol/markdown-it-admon>`_. """ def renderDefault(self, tokens, idx, _options, env): return self.renderToken(tokens, idx, _options, env) render = render or renderDefault md.add_render_rule("details_open", render) md.add_render_rule("details_close", render) md.add_render_rule("details_title_open", render) md.add_render_rule("details_title_close", render) md.block.ruler.before( "fence", "details", details, {"alt": ["paragraph", "reference", "blockquote", "list"]}, )