Skip to content

rendering ¤

Markdown extensions and helpers.

Classes:

  • MarkdownConfig –

    This class returns a singleton used to store Markdown extensions configuration.

  • MarkdownConverter –

    Helper class to avoid breaking the original Markdown instance state.

Functions:

  • add_source –

    Add source code block to the output.

  • code_block –

    Format code as a code block.

  • tabbed –

    Format tabs using pymdownx.tabbed extension.

Attributes:

  • markdown_config –

    This object can be used to save the configuration of your Markdown extensions.

markdown_config module-attribute ¤

markdown_config = MarkdownConfig()

This object can be used to save the configuration of your Markdown extensions.

For example, since we provide a MkDocs plugin, we use it to store the configuration that was read from mkdocs.yml:

from markdown_exec.rendering import markdown_config

# ...in relevant events/hooks, access and modify extensions and their configs, then:
markdown_config.save(extensions, extensions_config)

See the actual event hook: on_config. See the save and reset methods.

Without it, Markdown Exec will rely on the registeredExtensions attribute of the original Markdown instance, which does not forward everything that was configured, notably extensions like tables. Other extensions such as attr_list are visible, but fail to register properly when reusing their instances. It means that the rendered HTML might differ from what you expect (tables not rendered, attribute lists not injected, emojis not working, etc.).

MarkdownConfig ¤

MarkdownConfig()

This class returns a singleton used to store Markdown extensions configuration.

You don't have to instantiate the singleton yourself: we provide it as markdown_config.

Methods:

  • reset –

    Reset Markdown extensions and their configuration.

  • save –

    Save Markdown extensions and their configuration.

reset ¤

reset() -> None

Reset Markdown extensions and their configuration.

save ¤

save(
    exts: list[str], exts_config: dict[str, dict[str, Any]]
) -> None

Save Markdown extensions and their configuration.

Parameters:

  • exts (list[str]) –

    The Markdown extensions.

  • exts_config (dict[str, dict[str, Any]]) –

    The extensions configuration.

MarkdownConverter ¤

MarkdownConverter(md: Markdown, *, update_toc: bool = True)

Helper class to avoid breaking the original Markdown instance state.

Methods:

  • convert –

    Convert Markdown text to safe HTML.

convert ¤

convert(
    text: str,
    stash: dict[str, str] | None = None,
    id_prefix: str | None = None,
) -> Markup

Convert Markdown text to safe HTML.

Parameters:

  • text (str) –

    Markdown text.

  • stash (dict[str, str] | None, default: None ) –

    An HTML stash.

Returns:

  • Markup –

    Safe HTML.

add_source ¤

add_source(
    *,
    source: str,
    location: str,
    output: str,
    language: str,
    tabs: tuple[str, str],
    result: str = "",
    **extra: str
) -> str

Add source code block to the output.

Parameters:

  • source (str) –

    The source code block.

  • location (str) –

    Where to add the source (above, below, tabbed-left, tabbed-right, console).

  • output (str) –

    The current output.

  • language (str) –

    The code language.

  • tabs (tuple[str, str]) –

    Tabs titles (if used).

  • result (str, default: '' ) –

    Syntax to use when concatenating source and result with "console" location.

  • **extra (str, default: {} ) –

    Extra options added back to source code block.

Raises:

  • ValueError –

    When the given location is not supported.

Returns:

  • str –

    The updated output.

code_block ¤

code_block(language: str, code: str, **options: str) -> str

Format code as a code block.

Parameters:

  • language (str) –

    The code block language.

  • code (str) –

    The source code to format.

  • **options (str, default: {} ) –

    Additional options passed from the source, to add back to the generated code block.

Returns:

  • str –

    The formatted code block.

tabbed ¤

tabbed(*tabs: tuple[str, str]) -> str

Format tabs using pymdownx.tabbed extension.

Parameters:

  • *tabs (tuple[str, str], default: () ) –

    Tuples of strings: title and text.

Returns:

  • str –

    The formatted tabs.