mkdocs-livecodes

Convert MkDocs Markdown code fences to interactive LiveCodes playgrounds, links, or buttons.

This package is intended to provide MkDocs and Material for MkDocs users with syntax similar to the existing JavaScript Markdown integrations for LiveCodes.

Installation

pip install mkdocs-livecodes

Usage

Enable the plugin in mkdocs.yml:

plugins:
- search
- livecodes:
render: playgroundheight: 500pxparams:
console: opentheme: light

Then add livecodes to a fenced code block:

```js livecodes
console.log("Hello from LiveCodes");
```

Render modes

Playground iframe

```jsx livecodes
exportdefaultfunctionApp() {
return<h1>Hello</h1>;
}
```

Button

```python livecodes render=button
print("Hello from Python")
```

Link

```ts livecodes render=link
console.log("Hello");
```

Metadata marker

```js livecodes render=meta
console.log("Hello");
```

render=meta preserves the code block and appends a hidden element with data-livecodes-url.

Global options

plugins:
- livecodes:
render: playground # playground | button | link | metaauto: false # transform all fences unless livecodes=falseheight: 500pxclass_name: livecodes-frameapp_url: https://livecodes.iotext: Edit in LiveCodesparams:
console: opentheme: lightview: split

Both Python-style and JavaScript-style names are accepted where useful:

• class_name and className
• app_url and appUrl

Per-block meta parameters

Per-block parameters override global options:

```jsx livecodes render=button className=dark-btn console=open theme=dark
exportdefault () =><h1>Hello</h1>;
```

Use lang to override the code fence language sent to LiveCodes:

```py livecodes lang=python
print("Hello")
```

When auto: true, opt out per block with:

```js livecodes=false
console.log("do not transform this block");
```

Material for MkDocs

Example configuration:

theme:
name: materialplugins:
- search
- livecodes:
render: buttonparams:
console: openmarkdown_extensions:
- pymdownx.highlight
- pymdownx.superfences

For render: button, render: link, and render: meta, the original code block is preserved, so syntax highlighting extensions can still process it.

Development

pip install -e .[test]
pytest

Notes

The plugin transforms Markdown in MkDocs' on_page_markdown phase, before Markdown is rendered to HTML. It intentionally preserves non-LiveCodes fences exactly.