Playground Plugin
The @docmd/plugin-playground plugin brings interactive, runnable code blocks and live component previews directly to your docmd site. It enables documentation authors to embed self-contained JavaScript executions, live HTML/CSS components, and active script files from their repository without the bulky dependencies (like Monaco or React) found in heavier documentation frameworks.
Starting in v0.9.9, @docmd/plugin-playground ships directly with @docmd/core and is enabled by default. Thanks to docmd’s conditional asset loading, pages without playground blocks load 0 KB of extra assets, ensuring zero performance impact on static content.
Key Features
Write code blocks with ```js playground or container blocks with ::: playground to immediately instantiate an interactive sandbox.
Point directly to source scripts in your codebase using ::: playground src="./snippets/demo.js" /::: to keep documentation automatically in sync with real project code.
Intercepts and formats console.log(), console.info(), console.warn(), and console.error() outputs in real time, alongside evaluated return values.
Renders live HTML/CSS widgets inside an isolated preview panel with tab toggling between console logs and rendered UI.
Direct, native access to the client-side window.docmd runtime and reactive page variables via docmd.var.get() and docmd.var.set().
Interactive header tabs allow instant switching between running component previews and underlying source code in a clean single-panel view.
Missing scripts render non-breaking warning banners with clean fallback code; runtime exceptions display structured execution notices.
Pure vanilla JavaScript and CSS (< 10 KB total bundle) with keyboard shortcuts (Cmd+Enter / Ctrl+Enter to run, Tab for indentation).
Plugin Configuration
Because @docmd/plugin-playground is a core plugin, no configuration is required to start using it. However, you can customise global defaults or explicitly disable the plugin in docmd.config.json:
{
"plugins": {
"playground": {
"enabled": true,
"theme": "default",
"defaultLayout": "split"
}
}
}
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Enables or disables playground rendering globally. |
theme |
string |
"default" |
Colour theme matching your active docmd layout (default, dark, light). |
defaultLayout |
string |
"split" |
Default layout arrangement (split for side-by-side or stacked for vertical). |
To disable client-side code evaluation across your entire documentation site, set "playground": false under "plugins" in docmd.config.json. All playground code blocks will gracefully fallback to standard syntax-highlighted code blocks, and no playground scripts or stylesheets will be emitted.
Technical Architecture & Internals
The Playground plugin is engineered around a zero-dependency architecture that keeps documentation pages fast, secure, and light.
1. Build-Time AST Interception
During the static site build:
- Container Hook: Registers a custom rule on
markdown-it-containertargeting theplaygroundkeyword. - Code Fence Hook: Inspects code block language identifiers for
playgroundorliveflags (e.g.```js playground). - Asset Flagging: When any playground container or fence is detected on a page,
docmdflags the document metadata. Only pages with this flag include the<link>and<script>tags for the playground runtime. Static pages remain 100% clean with 0 KB asset overhead.
2. Script Resolution Engine
When a container specifies an external script path using src="./..." or file="./...":
docmdresolves the file path relative to the active Markdown document’s directory.- If not found relative to the document, it falls back to resolving against the project root.
- The script content is read and safely escaped into the code editor DOM element at build time.
- Graceful Warning Handling: If the specified script cannot be found (e.g. relocated or deleted during refactoring), the builder does not abort. Instead, it generates a structured warning callout (
.docmd-playground-missing-alert) detailing the missing path and renders empty fallback code, ensuring continuous deployment pipelines never fail due to missing doc snippets.
3. Client Runtime & Execution Sandbox
When a user clicks Run or executes via keyboard shortcut (Cmd+Enter / Ctrl+Enter):
- Console Hijacking: The runtime instantiates a sandboxed proxy around
console.log,console.info,console.warn, andconsole.error. Messages are intercepted, formatted with syntax styling, and appended to the playground’s output pane in real time while still mirroring to DevTools if open. - Isolated Function Context: JavaScript is evaluated inside an asynchronous function wrapper with access to
window.docmdand global browser APIs. - HTML/CSS Component Previews: For HTML snippets, content is rendered into an isolated sandbox panel, enabling full interactive testing of buttons, forms, and custom widgets.
- Pure Client-Side: No server execution or backend attack surface exists; all code runs entirely in the visitor’s browser.
- Iframe Sandboxing: HTML previews run inside an isolated iframe with
sandbox="allow-scripts allow-modals allow-forms"withoutallow-same-origin, blocking access to parent page cookies, LocalStorage, and parent DOM. - Domain Isolation Best Practice: For production deployments, host documentation on a dedicated documentation subdomain (e.g.
docs.example.com).
Script-Based Examples & Workflows
Script Example 1: Active Codebase Sourcing with src
Link directly to real scripts in your repository to eliminate out-of-sync copy-pasting:
::: playground src="./snippets/demo.js" title="Active Sourced Script" icon:cpu live /:::
When built, docmd automatically reads snippets/demo.js and embeds it directly into the sandbox:
Script Example 2: Interactive HTML & CSS Component Preview
Playgrounds render rich HTML and CSS components directly in the browser sandbox. Readers view the rendered interface in the Play view and can toggle to the Code view to inspect or tweak markup:
::: playground title="Interactive Notification Card" icon:bell live
```html
<div style="padding: 16px; border-radius: 8px; background: #0f172a; border: 1px solid #1e293b; color: #f8fafc; font-family: system-ui, sans-serif;">
<div style="display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px;">
<strong style="color: #38bdf8; font-size: 14px;">Real-Time Notification</strong>
<span style="font-size: 11px; background: #0369a1; padding: 2px 8px; border-radius: 10px; color: white;">Online</span>
</div>
<p style="margin: 0 0 12px 0; font-size: 13px; color: #94a3b8; line-height: 1.4;">
Toggle between <strong>Play</strong> and <strong>Code</strong> views in the header toolbar to inspect or modify the underlying markup.
</p>
<button style="padding: 6px 14px; background: #10b981; color: white; border: none; border-radius: 6px; font-size: 12px; font-weight: 600; cursor: pointer;" onclick="alert('Notification action triggered!')">
Trigger Action
</button>
</div>
```
:::
Live rendered component:
Script Example 3: Dynamic Script Execution with Console Logs
Execute JavaScript scripts in a client sandbox with full interception of console.log, console.info, and return values:
Container & Plugin Cross-Reference
- Playground Container Documentation: Explore complete container syntax options, header tabs, layout configurations (
splitvsstacked), and Markdown container examples. - Variables & Personalisation Engine: Learn how
docmd-runtimeintegrates with playground scripts for client-side reactivity. - Containers Overview: Overview of all native containers supported in
docmd.