mkdocs-onlinecompiler 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """Runnable code blocks for MkDocs and Material for MkDocs, powered by OnlineCompiler.io."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,88 @@
1
+ """Finds the fenced code blocks marked ``runnable`` in a page's Markdown."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass
7
+ from typing import Callable
8
+
9
+ OPENING = re.compile(r"^(?P<indent>[ \t]*)(?P<fence>`{3,}|~{3,})(?P<info>.*)$")
10
+ # "runnable" or ".runnable" as a word of the info string: ```python runnable or ``` {.python .runnable}
11
+ FLAG = re.compile(r"(?:^|(?<=[\s{]))\.?runnable(?=[\s}]|$)")
12
+ LANG = re.compile(r"""(?:^|(?<=[\s{]))lang=(?:"([^"]*)"|'([^']*)'|([^\s}]+))""")
13
+
14
+
15
+ @dataclass
16
+ class Block:
17
+ """A fenced code block marked runnable."""
18
+
19
+ language: str # the block's own language ("python"), or ""
20
+ lang: str | None # what lang= asks for, if anything
21
+ code: str
22
+
23
+
24
+ def language_of(info: str) -> str:
25
+ """The language an info string names: "python" for "python title=x" and for "{.python .x}"."""
26
+ words = info.strip().strip("{}").split()
27
+ for word in words:
28
+ name = word.lstrip(".")
29
+ if word.startswith("{") or "=" in word or name == "runnable":
30
+ continue
31
+ return name
32
+ return ""
33
+
34
+
35
+ def without_flags(info: str) -> str:
36
+ """The info string with runnable and lang= taken out, for a block that stays plain code."""
37
+ return re.sub(r"\s+", " ", LANG.sub("", FLAG.sub("", info))).replace("{ ", "{").replace(" }", "}").strip()
38
+
39
+
40
+ def _dedent(line: str, indent: str) -> str:
41
+ """The line without the fence's indentation (or as much of it as the line has)."""
42
+ width = len(indent)
43
+ stripped = line.lstrip(" \t")
44
+ return line[width:] if len(line) - len(stripped) >= width else stripped
45
+
46
+
47
+ def replace_runnable(markdown: str, convert: Callable[[Block], str | None]) -> str:
48
+ """Calls ``convert`` for each fenced block marked runnable, and puts the line it returns in
49
+ place of the block, at the block's indentation. When it returns None the block stays code,
50
+ with runnable and lang= taken out of its info string. Blocks inside other code blocks (a
51
+ page showing the syntax itself) are left alone."""
52
+ lines = markdown.split("\n")
53
+ out: list[str] = []
54
+ i = 0
55
+ while i < len(lines):
56
+ opening = OPENING.match(lines[i])
57
+ info = opening.group("info") if opening else ""
58
+ # A backtick fence's info string can't hold a backtick (CommonMark), so ``` `x` ``` is code.
59
+ if not opening or (opening.group("fence")[0] == "`" and "`" in info):
60
+ out.append(lines[i])
61
+ i += 1
62
+ continue
63
+ indent, fence = opening.group("indent"), opening.group("fence")
64
+ closing = re.compile(rf"^[ \t]*{re.escape(fence[0])}{{{len(fence)},}}[ \t]*$")
65
+ end = next((j for j in range(i + 1, len(lines)) if closing.match(lines[j])), None)
66
+ if end is None: # an unclosed fence runs to the end of the page
67
+ out.extend(lines[i:])
68
+ break
69
+ if not FLAG.search(info):
70
+ out.extend(lines[i : end + 1])
71
+ i = end + 1
72
+ continue
73
+
74
+ asked = LANG.search(info)
75
+ block = Block(
76
+ language=language_of(info),
77
+ lang=(asked.group(1) or asked.group(2) or asked.group(3) or "") if asked else None,
78
+ code="\n".join(_dedent(line, indent) for line in lines[i + 1 : end]),
79
+ )
80
+ replacement = convert(block)
81
+ if replacement is None:
82
+ out.append(f"{indent}{fence}{without_flags(info)}")
83
+ out.extend(lines[i + 1 : end + 1])
84
+ else:
85
+ # Blank lines around it, so it is a paragraph of its own wherever the fence was.
86
+ out.extend(["", f"{indent}{replacement}", ""])
87
+ i = end + 1
88
+ return "\n".join(out)
@@ -0,0 +1,115 @@
1
+ """The languages OnlineCompiler.io runs, and the names code blocks use for them."""
2
+
3
+ from __future__ import annotations
4
+
5
+ # Compiler id: (label, short name). Copied from https://onlinecompiler.io/docs/compilers at each
6
+ # release. A code block's language can be a compiler id or a short name; the first id with a short
7
+ # name is the one it picks.
8
+ LANGUAGES: dict[str, tuple[str, str]] = {
9
+ "python-3.14": ("Python 3.14", "python"),
10
+ "gcc-15": ("C (GCC 15)", "c"),
11
+ "g++-15": ("C++ (G++ 15)", "cpp"),
12
+ "openjdk-25": ("Java (OpenJDK 25)", "java"),
13
+ "dotnet-csharp-10": ("C# (.NET SDK 10)", "csharp"),
14
+ "dotnet-fsharp-10": ("F# (.NET SDK 10)", "fsharp"),
15
+ "go-1.26": ("Go 1.26", "go"),
16
+ "rust-1.93": ("Rust 1.93", "rust"),
17
+ "php-8.5": ("PHP 8.5", "php"),
18
+ "ruby-4.0": ("Ruby 4.0", "ruby"),
19
+ "haskell-9.12": ("Haskell (GHC 9.12)", "haskell"),
20
+ "typescript-deno": ("TypeScript (Deno)", "typescript"),
21
+ "nodejs-24": ("JavaScript (Node.js 24)", "javascript"),
22
+ "sqlite-3": ("SQL (SQLite 3)", "sql"),
23
+ "duckdb-1.5": ("DuckDB 1.5", "duckdb"),
24
+ "bash-5.2": ("Bash 5.2", "bash"),
25
+ "gfortran-15": ("Fortran (gfortran 15)", "fortran"),
26
+ "dotnet-vbnet-10": ("Visual Basic (.NET SDK 10)", "vbnet"),
27
+ "kotlin-2.4": ("Kotlin 2.4", "kotlin"),
28
+ "r-4.6": ("R 4.6", "r"),
29
+ "swift-6.4": ("Swift 6.4", "swift"),
30
+ "gnucobol-3.2": ("COBOL (GnuCOBOL 3.2)", "cobol"),
31
+ "perl-5.44": ("Perl 5.44", "perl"),
32
+ "julia-1.13": ("Julia 1.13", "julia"),
33
+ "fpc-3.2": ("Pascal (Free Pascal 3.2)", "pascal"),
34
+ "octave-11": ("Octave 11", "octave"),
35
+ "nasm-3": ("Assembly (NASM 3)", "assembly"),
36
+ "lua-5.5": ("Lua 5.5", "lua"),
37
+ "ocaml-5.4": ("OCaml 5.4", "ocaml"),
38
+ "sbcl-2.6": ("Common Lisp (SBCL 2.6)", "common-lisp"),
39
+ "erlang-29": ("Erlang (OTP 29)", "erlang"),
40
+ "elixir-1.20": ("Elixir 1.20", "elixir"),
41
+ "swipl-10": ("Prolog (SWI-Prolog 10)", "prolog"),
42
+ "ldc-1.43": ("D (LDC 1.43)", "d"),
43
+ "fbc-1.10": ("FreeBASIC 1.10", "freebasic"),
44
+ "dart-3.13": ("Dart 3.13", "dart"),
45
+ "clojure-1.12": ("Clojure 1.12", "clojure"),
46
+ "groovy-6.0": ("Groovy 6.0", "groovy"),
47
+ "scala-3.10": ("Scala 3.10", "scala"),
48
+ "zig-0.17": ("Zig 0.17", "zig"),
49
+ "nim-2.2": ("Nim 2.2", "nim"),
50
+ "crystal-1.22": ("Crystal 1.22", "crystal"),
51
+ "gnat-15": ("Ada (GNAT 15)", "ada"),
52
+ "powershell-7.6": ("PowerShell 7.6", "powershell"),
53
+ "racket-9.3": ("Racket 9.3", "racket"),
54
+ "clang-objc-21": ("Objective-C (Clang 21)", "objective-c"),
55
+ "g++-15-cpp20": ("C++20 (G++ 15)", "cpp"),
56
+ "python-3.14-pandas2": ("Python 3.14 with pandas 2", "python"),
57
+ }
58
+
59
+ # Other names code blocks use for these languages (Pygments' and highlight.js's among them).
60
+ ALIASES: dict[str, str] = {
61
+ "py": "python-3.14",
62
+ "python3": "python-3.14",
63
+ "c++": "g++-15",
64
+ "c++20": "g++-15-cpp20",
65
+ "cpp20": "g++-15-cpp20",
66
+ "js": "nodejs-24",
67
+ "node": "nodejs-24",
68
+ "ts": "typescript-deno",
69
+ "c#": "dotnet-csharp-10",
70
+ "cs": "dotnet-csharp-10",
71
+ "f#": "dotnet-fsharp-10",
72
+ "golang": "go-1.26",
73
+ "rs": "rust-1.93",
74
+ "rb": "ruby-4.0",
75
+ "hs": "haskell-9.12",
76
+ "kt": "kotlin-2.4",
77
+ "jl": "julia-1.13",
78
+ "sqlite": "sqlite-3",
79
+ "sh": "bash-5.2",
80
+ "shell": "bash-5.2",
81
+ "f90": "gfortran-15",
82
+ "vb": "dotnet-vbnet-10",
83
+ "asm": "nasm-3",
84
+ "nasm": "nasm-3",
85
+ "matlab": "octave-11",
86
+ "lisp": "sbcl-2.6",
87
+ "erl": "erlang-29",
88
+ "ex": "elixir-1.20",
89
+ "exs": "elixir-1.20",
90
+ "clj": "clojure-1.12",
91
+ "cr": "crystal-1.22",
92
+ "ps1": "powershell-7.6",
93
+ "pwsh": "powershell-7.6",
94
+ "rkt": "racket-9.3",
95
+ "objc": "clang-objc-21",
96
+ "objectivec": "clang-objc-21",
97
+ }
98
+
99
+
100
+ def compiler_for(name: str | None, extra: dict[str, str] | None = None) -> str | None:
101
+ """The compiler id for a language name ("python", "cpp", "python-3.14"), or None if
102
+ OnlineCompiler.io doesn't run it. ``extra`` is the site's own map, checked first."""
103
+ key = (name or "").strip().lower()
104
+ if not key:
105
+ return None
106
+ if extra and key in extra:
107
+ return compiler_for(extra[key])
108
+ if key in LANGUAGES:
109
+ return key
110
+ if key in ALIASES:
111
+ return ALIASES[key]
112
+ for compiler_id, (_, short) in LANGUAGES.items():
113
+ if short == key:
114
+ return compiler_id
115
+ return None
@@ -0,0 +1,134 @@
1
+ """The MkDocs plugin: code blocks marked ``runnable`` become editors readers can run.
2
+
3
+ A Markdown preprocessor finds the runnable blocks after snippets are included and before any code
4
+ block extension sees them, and stashes the widget's markup in their place: a div whose <pre> holds
5
+ the code. So no other extension can change the code, and the code is in the page as text.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import html
11
+
12
+ from markdown import Extension, Markdown
13
+ from markdown.preprocessors import Preprocessor
14
+ from mkdocs.config import base
15
+ from mkdocs.config import config_options as c
16
+ from mkdocs.exceptions import PluginError
17
+ from mkdocs.plugins import BasePlugin, get_plugin_logger
18
+
19
+ from .fences import Block, replace_runnable
20
+ from .languages import compiler_for
21
+
22
+ log = get_plugin_logger(__name__)
23
+
24
+ WIDGET_URL = "https://onlinecompiler.io/widget.js"
25
+ KEYS_URL = "https://api.onlinecompiler.io/compilers/widgets/"
26
+
27
+ # Sets each "site" runner's data-theme from the page's light or dark mode, now and when the reader
28
+ # switches: Material for MkDocs keeps it on <body data-md-color-scheme>, MkDocs' own theme on
29
+ # <html data-bs-theme>. It runs again on each page Material's instant navigation brings in.
30
+ THEME_SCRIPT = """<script>(function () {
31
+ function mode() {
32
+ var scheme = document.body.getAttribute("data-md-color-scheme");
33
+ if (scheme) return scheme === "slate" ? "dark" : "light";
34
+ return document.documentElement.getAttribute("data-bs-theme") === "dark" ? "dark" : "light";
35
+ }
36
+ function apply() {
37
+ var theme = mode();
38
+ document.querySelectorAll('[data-onlinecompiler-theme="site"]').forEach(function (el) {
39
+ if (el.getAttribute("data-theme") !== theme) el.setAttribute("data-theme", theme);
40
+ });
41
+ }
42
+ apply();
43
+ if (window.onlinecompilerThemeWatch) return;
44
+ window.onlinecompilerThemeWatch = new MutationObserver(apply);
45
+ window.onlinecompilerThemeWatch.observe(document.body, { attributes: true, attributeFilter: ["data-md-color-scheme"] });
46
+ window.onlinecompilerThemeWatch.observe(document.documentElement, { attributes: true, attributeFilter: ["data-bs-theme"] });
47
+ })();</script>"""
48
+
49
+
50
+ class OnlineCompilerConfig(base.Config):
51
+ key = c.Type(str, default="")
52
+ theme = c.Choice(("site", "light", "dark", "auto"), default="site")
53
+ languages = c.Type(dict, default={})
54
+
55
+
56
+ class RunnableExtension(Extension):
57
+ def __init__(self, plugin: OnlineCompilerPlugin):
58
+ super().__init__()
59
+ self.plugin = plugin
60
+
61
+ def extendMarkdown(self, md: Markdown) -> None:
62
+ # After snippets (32) and whitespace normalising (30), before fenced code blocks (25).
63
+ md.preprocessors.register(RunnablePreprocessor(md, self.plugin), "onlinecompiler", 28)
64
+
65
+
66
+ class RunnablePreprocessor(Preprocessor):
67
+ def __init__(self, md: Markdown, plugin: OnlineCompilerPlugin):
68
+ super().__init__(md)
69
+ self.plugin = plugin
70
+
71
+ def run(self, lines: list[str]) -> list[str]:
72
+ convert = lambda block: self.plugin.runner(block, self.md) # noqa: E731
73
+ return replace_runnable("\n".join(lines), convert).split("\n")
74
+
75
+
76
+ class OnlineCompilerPlugin(BasePlugin[OnlineCompilerConfig]):
77
+ def on_config(self, config):
78
+ self.languages: dict[str, str] = {}
79
+ for name, compiler in self.config.languages.items():
80
+ resolved = compiler_for(str(compiler))
81
+ if not resolved:
82
+ raise PluginError(f'onlinecompiler: "languages": OnlineCompiler.io has no compiler "{compiler}" (for "{name}").')
83
+ self.languages[str(name).strip().lower()] = resolved
84
+ self.key = self.config.key.strip()
85
+ if not self.key:
86
+ log.warning(
87
+ f'No widget key, so runnable code blocks show as plain code. Create a free one at {KEYS_URL} '
88
+ 'and set it as the plugin\'s "key" option.'
89
+ )
90
+ self.page = None
91
+ self.page_runners = 0
92
+ config.markdown_extensions.append(RunnableExtension(self))
93
+ return config
94
+
95
+ def on_page_markdown(self, markdown, page, config, files):
96
+ # MkDocs renders one page at a time: this page's Markdown is converted next.
97
+ self.page = page
98
+ self.page_runners = 0
99
+ return markdown
100
+
101
+ def on_page_content(self, content, page, config, files):
102
+ if not self.page_runners:
103
+ return content
104
+ # In the content rather than the page's <head>, so only pages with runners load the widget, and
105
+ # Material's instant navigation runs it when it brings in such a page.
106
+ loader = f'<script src="{WIDGET_URL}" async></script>'
107
+ return content + loader + (THEME_SCRIPT if self.config.theme == "site" else "")
108
+
109
+ def runner(self, block: Block, md: Markdown) -> str | None:
110
+ """The placeholder for a runnable block's runner, or None to leave it as code."""
111
+ if not self.key:
112
+ return None
113
+ name = block.lang if block.lang is not None else block.language
114
+ compiler = compiler_for(name, self.languages)
115
+ if not compiler:
116
+ reason = f"OnlineCompiler.io doesn't run \"{name}\"" if name else "the code block has no language"
117
+ where = f"{self.page.file.src_uri}: " if self.page else ""
118
+ log.warning(f"{where}a runnable code block shows as plain code: {reason}.")
119
+ return None
120
+ self.page_runners += 1
121
+ return md.htmlStash.store(self._markup(compiler, block.code))
122
+
123
+ def _markup(self, compiler: str, code: str) -> str:
124
+ theme = (
125
+ 'data-onlinecompiler-theme="site"' if self.config.theme == "site" else f'data-theme="{self.config.theme}"'
126
+ )
127
+ # A browser drops one newline straight after <pre>, so code starting with a blank line keeps it.
128
+ text = html.escape(code, quote=False)
129
+ if text.startswith("\n"):
130
+ text = "\n" + text
131
+ return (
132
+ f'<div class="runcode onlinecompiler-runner" data-key="{html.escape(self.key)}" '
133
+ f'data-lang="{html.escape(compiler)}" {theme} style="margin: 1em 0"><pre>{text}</pre></div>'
134
+ )
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.5
2
+ Name: mkdocs-onlinecompiler
3
+ Version: 0.1.0
4
+ Summary: Runnable, interactive code blocks for MkDocs and Material for MkDocs: readers edit and run your code examples in Python, JavaScript, C++, Java, Go, SQL and 46 languages, right in the docs
5
+ Project-URL: Homepage, https://onlinecompiler.io/guides/add-runnable-code-examples-to-mkdocs
6
+ Project-URL: Documentation, https://onlinecompiler.io/docs/widget
7
+ Project-URL: Source, https://github.com/onlinecompiler-io/mkdocs-onlinecompiler
8
+ Project-URL: Issues, https://github.com/onlinecompiler-io/mkdocs-onlinecompiler/issues
9
+ Author: RunCode Inc.
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: code playground,code runner,documentation,interactive code examples,live code,material-for-mkdocs,mkdocs,mkdocs-material,mkdocs-plugin,online compiler,onlinecompiler,python,run code,runnable code
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Plugins
15
+ Classifier: Framework :: MkDocs
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Education
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Topic :: Documentation
21
+ Classifier: Topic :: Software Development :: Documentation
22
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
23
+ Requires-Python: >=3.10
24
+ Requires-Dist: mkdocs>=1.5
25
+ Description-Content-Type: text/markdown
26
+
27
+ # Runnable code blocks for MkDocs and Material for MkDocs: interactive code examples in 46 languages
28
+
29
+ **mkdocs-onlinecompiler** turns the code examples in your MkDocs or Material for MkDocs site into interactive ones readers can edit and run, in Python, JavaScript, C++, Java, Go, SQL and 46 languages in all. Add the word `runnable` to a code block and readers get a live code editor with a Run button in the page, like a code playground, with no account and nothing to install.
30
+
31
+ ![A Material for MkDocs page with a runnable Python example and its output after Run](https://raw.githubusercontent.com/onlinecompiler-io/mkdocs-onlinecompiler/main/.github/screenshot.png)
32
+
33
+ ````markdown
34
+ ```python runnable
35
+ for n in range(1, 4):
36
+ print(n, "squared is", n * n)
37
+ ```
38
+ ````
39
+
40
+ The code runs on [OnlineCompiler.io](https://onlinecompiler.io/?utm_source=pypi), a code execution service, in an isolated sandbox with no network access. Nothing runs on your server or in the reader's browser, so the same docs can run C++, Rust or SQL as easily as Python.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pip install mkdocs-onlinecompiler
46
+ ```
47
+
48
+ Add it to `mkdocs.yml` with your widget key:
49
+
50
+ ```yaml
51
+ plugins:
52
+ - search
53
+ - onlinecompiler:
54
+ key: YOUR_WIDGET_KEY
55
+ ```
56
+
57
+ Create a free widget key on the [Widgets page](https://api.onlinecompiler.io/compilers/widgets/) of your OnlineCompiler.io dashboard (sign in with Google), and set its allowed domain to your docs site's domain so other sites can't use it. Listing `plugins` replaces MkDocs' default list, so keep `search` in it if you use search.
58
+
59
+ ## Write runnable examples
60
+
61
+ Add `runnable` after the language of any fenced code block:
62
+
63
+ ````markdown
64
+ ```cpp runnable
65
+ #include <iostream>
66
+
67
+ int main() {
68
+ std::cout << "Hello from C++\n";
69
+ }
70
+ ```
71
+ ````
72
+
73
+ - **The block's language picks the compiler**: `python` runs Python 3.14, `cpp` runs C++ (G++ 15), `js` runs Node.js 24, `sql` runs SQLite. Compiler ids work too: `python-3.14`, `g++-15`.
74
+ - **`lang=` picks another one**: ```` ```python runnable lang=python-3.14-pandas2 ```` runs Python with pandas 2.
75
+ - **Attribute style works too**: ```` ``` {.python .runnable} ````, and other options stay: ```` ```python title="hello.py" runnable ````.
76
+ - **Code blocks without `runnable` stay as they are.** A runnable block in a language OnlineCompiler.io doesn't run stays plain code, and the build prints a warning naming the page and the language (so `mkdocs build --strict` stops on it).
77
+
78
+ Readers can change the code, type the program's input and run it again. Runners work in admonitions, content tabs and pages built from snippets, and with Material's instant navigation.
79
+
80
+ ## Options
81
+
82
+ | Option | Default | What it does |
83
+ | --- | --- | --- |
84
+ | `key` | none | Your widget key. Without one, runnable blocks show as plain code and the build warns. |
85
+ | `theme` | `site` | `site` follows the light or dark mode of Material for MkDocs or MkDocs' own theme. `light`, `dark` or `auto` (the reader's system setting) fix it. |
86
+ | `languages` | `{}` | Your own code block languages, mapped to compiler ids: `{py3: python-3.14}`. |
87
+
88
+ To keep the key out of the config file, read it from the environment: `key: !ENV [ONLINECOMPILER_WIDGET_KEY, ""]`.
89
+
90
+ ## Supported languages
91
+
92
+ Python, C, C++ (and C++20), Java, JavaScript (Node.js), TypeScript (Deno), C#, F#, Visual Basic, Go, Rust, PHP, Ruby, Kotlin, Swift, Dart, Scala, Groovy, Clojure, Haskell, OCaml, Elixir, Erlang, Racket, Common Lisp, Prolog, R, Julia, Octave, Fortran, COBOL, Pascal, Ada, D, Nim, Zig, Crystal, Perl, Lua, Bash, PowerShell, Objective-C, FreeBASIC, Assembly (NASM), SQL (SQLite) and DuckDB. Python includes NumPy, pandas, SciPy, scikit-learn and Matplotlib.
93
+
94
+ The full list of compiler ids is at [onlinecompiler.io/docs/compilers](https://onlinecompiler.io/docs/compilers?utm_source=pypi).
95
+
96
+ ## FAQ
97
+
98
+ ### How do I run Python code in MkDocs or Material for MkDocs?
99
+
100
+ Install this plugin, add your widget key to `mkdocs.yml`, and write `runnable` after the language of a Python code block (```` ```python runnable ````). Readers can then edit the code and run it in the page. The same works for C++, Java, Go, Rust, SQL and every other language in the list above.
101
+
102
+ ### How is this different from markdown-exec, mkdocs-pyscript or pyodide-mkdocs-theme?
103
+
104
+ - **markdown-exec** runs code when the site is built and puts the output in the page, so readers see the result but can't change the code and run it again. (Its Pyodide blocks run Python in the browser, as below.)
105
+ - **Python in the browser** (mkdocs-pyscript, pyodide-mkdocs-theme, Pyodide blocks) runs Python only, inside the reader's browser, which first downloads a Python runtime.
106
+ - **This plugin** sends the code to a server sandbox, so it runs the real compilers and interpreters of 46 languages, including Python with NumPy and pandas, and readers can change the code and run it as often as they like. The reader's browser only shows the editor and the output.
107
+
108
+ ### Does it slow down my docs?
109
+
110
+ No. Only pages with a runnable block load the widget script, without holding up the page, and each runner connects only when it scrolls into view. Pages without runnable blocks load nothing extra.
111
+
112
+ ### Can search engines and MkDocs search read the code?
113
+
114
+ Yes. The code is in the page's HTML as text, so search engines and the site's own search index it, and readers see it before the editor loads.
115
+
116
+ ### What do readers' runs cost?
117
+
118
+ Widget keys are free. Runs count towards your OnlineCompiler.io account's allowance; the Free plan includes 100,000 runs a month. Give the key its own monthly limit to cap what a public page can use.
119
+
120
+ ### Is the widget key secret?
121
+
122
+ No. Widget keys are made to sit in public pages: they can run code in the widget but can't call the REST API. Restrict the key to your domain.
123
+
124
+ ### What if OnlineCompiler.io can't be reached?
125
+
126
+ The code is in the page as text, so readers still see it. Only the Run button needs the service.
127
+
128
+ ### Does it work with Docusaurus or WordPress too?
129
+
130
+ Yes: [docusaurus-plugin-onlinecompiler](https://github.com/onlinecompiler-io/docusaurus-plugin-onlinecompiler) for Docusaurus, and the [OnlineCompiler.io Code Runner](https://github.com/onlinecompiler-io/onlinecompiler-wordpress) plugin for WordPress. Any other site can use the [embeddable code editor](https://onlinecompiler.io/embeddable-code-editor?utm_source=pypi) directly.
131
+
132
+ ## What it sends, and where
133
+
134
+ On pages with a runnable block, the reader's browser loads the widget script from `https://onlinecompiler.io/widget.js`. When a runner scrolls into view, the widget connects to `api.onlinecompiler.io` with your widget key; the browser adds your site's address, which is how the key's allowed domain is checked. When a reader presses Run, the widget sends the code, its input and the language, and shows the result. Readers don't sign in and the plugin sends nothing else about them. See the OnlineCompiler.io [privacy policy](https://onlinecompiler.io/privacy) and [terms](https://onlinecompiler.io/terms).
135
+
136
+ The widget itself, its options and its JavaScript API are documented at [onlinecompiler.io/docs/widget](https://onlinecompiler.io/docs/widget?utm_source=pypi).
137
+
138
+ ## Requirements
139
+
140
+ MkDocs 1.5 or later on Python 3.10 or later. Tested with MkDocs 1.5 and 1.6 and Material for MkDocs 9.
141
+
142
+ ## License
143
+
144
+ MIT
@@ -0,0 +1,9 @@
1
+ mkdocs_onlinecompiler/__init__.py,sha256=CO8RxUQ-PQtPCLnyr1O-4RqLIdYQZR1-qPaFXaMzBww,116
2
+ mkdocs_onlinecompiler/fences.py,sha256=VaeyBjiKJqXzSfarTY-l1qZsYG7l90hbT7Yk3je25KQ,3639
3
+ mkdocs_onlinecompiler/languages.py,sha256=9p70KvmAQZmdH69XgD2OQ_cpfViat74eNcO115jMkMk,4764
4
+ mkdocs_onlinecompiler/plugin.py,sha256=rNjT43v_otRFaWmERlxsY756jBzG22bseAcuEFq-G3w,6065
5
+ mkdocs_onlinecompiler-0.1.0.dist-info/METADATA,sha256=okgM07Bjli7Ll7lTyGGkq_GUDH5Y0kjfCbL9355m5Vw,8690
6
+ mkdocs_onlinecompiler-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ mkdocs_onlinecompiler-0.1.0.dist-info/entry_points.txt,sha256=5y1PzW9-1dHz4yyCUALN3byxzt8C2Gtm-8xOO6cC1Ao,84
8
+ mkdocs_onlinecompiler-0.1.0.dist-info/licenses/LICENSE,sha256=ewJ8Ho-t36T048PVcYWDREgjhelKO_i5q2cH8pafvU0,1069
9
+ mkdocs_onlinecompiler-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [mkdocs.plugins]
2
+ onlinecompiler = mkdocs_onlinecompiler.plugin:OnlineCompilerPlugin
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RunCode Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.