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: playground
      height: 500px
      params:
        console: open
        theme: light

Then add livecodes to a fenced code block:

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

Render modes

Playground iframe

```jsx livecodes
export default function App() {
  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 | meta
      auto: false             # transform all fences unless livecodes=false
      height: 500px
      class_name: livecodes-frame
      app_url: https://livecodes.io
      text: Edit in LiveCodes
      params:
        console: open
        theme: light
        view: 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
export default () => <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: material

plugins:
  - search
  - livecodes:
      render: button
      params:
        console: open

markdown_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.