mdlab

Runnable Markdown for VS Code.

mdlab adds in-file Run buttons to Markdown code fences, then writes the result back into the same document below the block. It is a lightweight alternative to notebooks when you want prose, code, and results in one diffable Markdown file.

Features

python fences run in a persistent IPython kernel per Markdown file.
bash fences run as shell commands in the document directory.
prompt {cache=true} fences call an AI CLI and cache by block hash.
Matplotlib figures are saved under .mdlab_assets/ and inlined as Markdown.
Results are stored directly in the document between HTML comment markers.
CodeLens actions support Run, Run all, Clear, Restart kernel, and Stop kernel.

Example

```python
import numpy as np
x = np.arange(5)
print(x.sum())
```

After running the block, mdlab writes:

<!-- mdlab:result src=abc123de kind=output -->
```output
10
```
<!-- mdlab:result-end -->

The packaged extension includes example.mdlab.md as a runnable sample and API.md as the full block reference.

Install From Source

Prerequisites:

VS Code or a compatible editor.
Node.js 18+ and npm.
Python 3 with jupyter_client, ipykernel, and optionally matplotlib.
An AI CLI on PATH if you want to use prompt blocks. The default command is claude.

Build once:

npm install
npm run compile

Then open this folder in VS Code and press F5 to launch an extension development host.

To package a VSIX:

npx --yes @vscode/vsce package
code --install-extension mdlab-0.10.0.vsix

Markdown File Setup

CodeLens only appears in the text editor, not the rendered Markdown preview. For a dedicated file extension such as *.mdlab.md, add this VS Code setting:

{
  "workbench.editorAssociations": {
    "**/*.mdlab.md": "default"
  }
}

Configuration

mdlab.python.interpreter: Python executable for the kernel daemon.
mdlab.claude.command: AI CLI command for prompt blocks.
mdlab.claude.extraArgs: extra CLI args appended after -p <body>.
mdlab.timeoutSeconds: per-block timeout in seconds.
mdlab.assetsDirName: figure/artifact directory relative to the document.

Result Regions

Do not hand-edit content between these markers unless you intend to replace the recorded output:

<!-- mdlab:result src=<hash> kind=<output|result|error> -->
...
<!-- mdlab:result-end -->

The src value is a hash of the runnable block. It lets cached prompt blocks skip re-execution when the prompt body has not changed.

License

MIT

Runnable Markdown Lab

Zhendong Qin