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

In the world of documentation, code examples often present a challenge. Readers are required to copy snippets, open a terminal or a separate playground, adjust indentation, and only then discover what the code does. Many give up before reaching this point. Docusaurus, a popular documentation tool, offers a solution for React applications with @docusaurus/theme-live-codeblock, which transforms a JSX live block into an interactive editor.

However, this feature is limited to JSX. If your documentation includes Python, Go, C++, SQL, or other non-React components, the copy and paste method remains the only option. To address this issue, I developed a small plugin called docusaurus-plugin-onlinecompiler. This plugin allows you to turn any fenced code block in your Markdown or MDX pages into a runnable editor with a single word.

After adding the plugin, a Run button appears in the editor, enabling readers to execute the code directly on the page. The code runs on OnlineCompiler.io in a fresh sandbox for each execution, ensuring no network access or impact on your server. This means Python, C++, SQL, or any other language can be run alongside JavaScript without any issues.

To use the plugin, install it via npm and add it to your docusaurus.config.js file with a widget key. The widget key is free and can be obtained from the Widgets page of the OnlineCompiler.io dashboard. Ensure the allowed domain is set to your docs domain, and create a second key for localhost previews. If you prefer to keep the key out of the config file, read it from the environment.

Adding a runnable code block is as simple as appending the word runnable after the language specifier in a fenced code block. For example, a Python code block becomes runnable by adding runnable after python. When the Run button is pressed, the output panel displays the program's execution results. Readers can modify the range and rerun the code, while input values are stored in the Input tab.

Unchanged code blocks remain as they are, allowing you to make selective examples runnable. The plugin supports various languages, each connecting to the appropriate compiler. The language selection also determines the compiler used, such as Python running Python 3.14 or C++ running C++ with G++ 15. If a language isn't supported, the block remains a regular code block, and a warning is generated during the build process to alert developers of potential issues.

Runnable code blocks are compatible with Docusaurus features like Tabs and admonitions. You can create interactive examples within tabs or highlight specific code using admonitions. The plugin works seamlessly within these structures and adapts to your site's theme. For instance, a JavaScript tab would execute a code snippet and display the output, while a Go tab would run a similar program and display "hi from Go."

The plugin is small, open-source, and built using Docusaurus's CodeBlock component. The source code is available on GitHub, where you can explore the details. However, there is one limitation: if both @docusaurus/theme-live-codeblock and this plugin are listed in your themes, the latter will take precedence. Use the live code block for React component demos and this plugin for other programming languages.

Using docusaurus-plugin-onlinecompiler is free and under the MIT license. Each Run press triggers a run on your OnlineCompiler.io account, and the free plan includes 100,000 runs per month with no credit card required. You can set a monthly limit for the widget key to control usage. For more information, visit https://onlinecompiler.io/guides/add-runnable-code-examples-to-docusaurus, or access the plugin on npm at https://www.npmjs.com/package/docusaurus-plugin-onlinecompiler.

The source code is hosted on GitHub at https://github.com/onlinecompiler-io/docusaurus-plugin-onlinecompiler.