mkdocs_plugin
MkDocs plugin for embedding runnable Drafter apps from fenced code blocks.
The fence info line may carry optional parameters (on drafter blocks and plain code fences alike)::
```python drafter hl_lines="2-4 7" height=300 source=collapsed
...
```
hl_lines highlights the given lines/ranges in the rendered source block
(via pymdownx.highlight) and height sets the embedded demo iframe's
height, overriding the plugin's iframe_height option for that block
(bare numbers are pixels; CSS lengths like 20em also work). source
controls how a demo's source block is presented: shown (the default),
collapsed (tucked into a closed "Show the code" block, via
pymdownx.details), or hidden (only the demo is shown).
COLLAPSED_SOURCE_TITLE = 'Show the code'
module-attribute
Summary label on the closed block wrapping a source=collapsed demo.
CSS_LENGTH_RE = re.compile('^\\d+(\\.\\d+)?(px|em|rem|vh|vw|%)$')
module-attribute
CSS lengths accepted for the height parameter (bare integers mean px).
FENCE_RE = re.compile('```(?P<info>[^\\n]*)\\n(?P<code>.*?)\\n```', flags=(re.DOTALL))
module-attribute
Regular expression matching fenced code blocks with an optional info string.
HL_LINES_TOKEN_RE = re.compile('^\\d+(-\\d+)?$')
module-attribute
A single hl_lines entry: a line number or an inclusive start-end range.
KNOWN_PARAMS = frozenset({'hl_lines', 'height', 'source'})
module-attribute
Fence parameters handled by this plugin (all others pass through untouched).
LOGGER = logging.getLogger('mkdocs.plugins.drafter_codeblocks')
module-attribute
Logger for the Drafter code block MkDocs plugin.
PARAM_RE = re.compile('(?P<key>[A-Za-z_][\\w-]*)=(?P<value>"[^"]*"|\'[^\']*\'|\\S+)')
module-attribute
Regular expression matching key=value parameters in a fence info string.
SOURCE_MODES = frozenset({'shown', 'collapsed', 'hidden'})
module-attribute
Accepted values for the source fence parameter on drafter blocks.
DrafterCodeBlockPlugin()
Bases: BasePlugin
Compile marked Drafter code fences into embedded runnable iframes.
on_config(config)
Prepare build state when the MkDocs configuration is loaded.
Resolves docs/site directories, creates the demo output directory and a temporary build directory, clears per-build caches, and determines the pyodide package style (honoring DRAFTER_MKDOCS_DEV).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
The MkDocs configuration object. |
required |
Returns:
| Type | Description |
|---|---|
|
The (unmodified) MkDocs configuration object. |
on_page_content(page_html, /, *, page, config, files)
Host the shared Pyodide runtime on pages that embed demos.
Loads the Drafter bundle in the PARENT page (before any demo iframes, so an iframe can never race ahead and boot its own runtime) and every embedded demo attaches to the resulting single shared runtime.
on_page_markdown(markdown, /, *, page, config, files)
Replace marked Drafter code fences with embedded demo iframes.
Each fenced block whose info string carries the configured marker is compiled into a standalone demo site and replaced by an iframe (optionally preceded by the original source block). Blocks that fail to build are left intact with a warning note appended.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
markdown
|
Raw markdown source of the page. |
required | |
page
|
The MkDocs page being processed. |
required | |
config
|
The MkDocs configuration object. |
required | |
files
|
The MkDocs files collection. |
required |
Returns:
| Type | Description |
|---|---|
|
The transformed markdown for the page. |
on_post_build(*, config)
Clean up the temporary build directory after the site is built.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
The MkDocs configuration object. |
required |