# Make the code examples in your Docusaurus docs runnable, in 46 languages

Most docs have the same problem with code examples. The reader copies the snippet, opens a terminal or a playground in another tab, pastes it, fixes the indentation, and only then finds out what it does. Many give up before that.

Docusaurus has a fix for React: `@docusaurus/theme-live-codeblock` turns a `jsx live` block into a live editor. But it only renders JSX in the browser. If your docs show Python, Go, C++, SQL or anything that isn't a React component, you're back to copy and paste.

So I built a small plugin for that: [docusaurus-plugin-onlinecompiler](https://github.com/onlinecompiler-io/docusaurus-plugin-onlinecompiler). You add one word to an ordinary code block, and readers get an editor with a Run button right in the page.

![A Docusaurus docs page with a runnable Python example and its output after Run](https://raw.githubusercontent.com/onlinecompiler-io/docusaurus-plugin-onlinecompiler/main/.github/screenshot.png)

The code runs on [OnlineCompiler.io](https://onlinecompiler.io) (I build it), in a fresh sandbox for each run with no network access. Nothing runs in the reader's browser or on your server, which is why the same docs can run Python, C++ or SQL as easily as JavaScript.

## Install it

```bash
npm install docusaurus-plugin-onlinecompiler
```

Add it to `docusaurus.config.js` with a widget key:

```js
export default {
  // ...the rest of your config
  plugins: [['docusaurus-plugin-onlinecompiler', { key: 'YOUR_WIDGET_KEY' }]],
};
```

The widget key is free, from the Widgets page of the OnlineCompiler.io dashboard. It's made to sit in public pages: it can run code in the widget but can't call the REST API. Set its allowed domain to your docs domain so other sites can't use it, and make a second key for `localhost` previews.

If you'd rather keep the key out of the config file, read it from the environment: `{ key: process.env.ONLINECOMPILER_WIDGET_KEY }`.

## Write `runnable`

Any fenced code block, in a `.md` or `.mdx` page, becomes a runner when you add `runnable` after its language:

````markdown
```python runnable
for n in range(1, 4):
    print(n, "squared is", n * n)
```
````

After Run, the output panel shows:

```text
1 squared is 1
2 squared is 4
3 squared is 9
```

Readers can change the range and run it again, and the Input tab holds whatever the program reads from standard input.

Code blocks without the word stay exactly as they are, so you can make one example runnable and leave the rest alone.

The code comes through as written, `<`, `&` and quotes included, because it goes into the page as text and the editor reads it from there:

````markdown
```cpp runnable
#include <iostream>
#include <vector>

int main() {
    std::vector<int> v{1, 2, 3};
    int sum = 0;
    for (int x : v) sum += x;
    std::cout << "sum & done: " << (sum < 10 ? "<10" : ">=10") << "\n";
}
```
````

That one printed `sum & done: <10`.

## Picking the compiler

The block's language picks the compiler: `python` runs Python 3.14, `cpp` runs C++ with G++ 15, `js` runs Node.js 24, `sql` runs SQLite, and full compiler ids like `openjdk-25` work too. When the language alone isn't enough, `lang=` names another compiler, and the other options on the line still work:

````markdown
```python title="frame.py" runnable lang=python-3.14-pandas2
import pandas as pd
print(pd.__version__)
```
````

That prints `2.3.3`, from the Python build that ships pandas 2.

If a block names a language the service doesn't run, it stays a normal code block, and the build prints a warning naming the language, so a typo doesn't fail silently.

## Inside Tabs and admonitions

Runnable blocks work anywhere Docusaurus renders a code block, including Tabs and admonitions:

````mdx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="js" label="JavaScript">

```js runnable
console.log([1, 2, 3].map((x) => x * 2));
```

</TabItem>
<TabItem value="go" label="Go">

```go runnable
package main

import "fmt"

func main() { fmt.Println("hi from Go") }
```

</TabItem>
</Tabs>
````

The JavaScript tab printed `[ 2, 4, 6 ]` and the Go tab `hi from Go`.

## How it works

The plugin is small, and the source is on GitHub, but three choices are worth knowing about if you care what ends up in your docs.

**It wraps Docusaurus's own `CodeBlock`.** The plugin provides a theme component that wraps the original one. A block without `runnable` goes straight to the normal `CodeBlock`, so your syntax highlighting, titles and line numbers don't change. A runnable block renders a plain `<div>` with the code in a `<pre>`, and the widget turns that into the editor.

**The code is in the HTML.** Because the server render puts the code in the page as text, search engines index your examples and readers see them before the editor loads. If the service can't be reached, the code is still there; only the Run button needs it.

**The widget script loads only where it's needed.** The script is added the first time a page with a runnable block mounts, not on every page of your site. Each runner connects only when it scrolls into view. As readers move between pages without a reload, new runners start and the ones that left the page close their connection. Runners also follow your site's light and dark mode as the reader switches it.

One limitation to know: `@docusaurus/theme-live-codeblock` also replaces the code block component, and a Docusaurus site can only have one such wrapper. If you list both, the one listed last in `themes` wins. Use the live code block for React component demos and this plugin for programs in other languages, not both on one site.

## What it costs

The plugin is free and MIT licensed. Each press of Run is one run on your OnlineCompiler.io account, and the free plan has 100,000 runs a month with no credit card. You can give the widget key its own monthly limit to cap what a public page can use.

## Links

- The full guide, with options and troubleshooting: https://onlinecompiler.io/guides/add-runnable-code-examples-to-docusaurus
- npm: https://www.npmjs.com/package/docusaurus-plugin-onlinecompiler
- Source: https://github.com/onlinecompiler-io/docusaurus-plugin-onlinecompiler

If you use MkDocs instead, there's a plugin for that too: [mkdocs-onlinecompiler](https://github.com/onlinecompiler-io/mkdocs-onlinecompiler). And if your docs run on something else, tell me which. We build integrations for other platforms free of charge.

