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.

Core Plugin Bundled with @docmd/core

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

Zero-Config Activation

Write code blocks with ```js playground or container blocks with ::: playground to immediately instantiate an interactive sandbox.

Active File Embedding

Point directly to source scripts in your codebase using ::: playground src="./snippets/demo.js" /::: to keep documentation automatically in sync with real project code.

Real-Time Console Capture

Intercepts and formats console.log(), console.info(), console.warn(), and console.error() outputs in real time, alongside evaluated return values.

Live HTML & CSS Sandbox

Renders live HTML/CSS widgets inside an isolated preview panel with tab toggling between console logs and rendered UI.

docmd-runtime Integration

Direct, native access to the client-side window.docmd runtime and reactive page variables via docmd.var.get() and docmd.var.set().

Live & Code View Toggle

Interactive header tabs allow instant switching between running component previews and underlying source code in a clean single-panel view.

Graceful Warning & Error Handling

Missing scripts render non-breaking warning banners with clean fallback code; runtime exceptions display structured execution notices.

Ultra-Lightweight & Fast

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:

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).
Disabling the Plugin

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.

flowchart TD MD[Markdown Source] --> AST[Markdown-It AST Parser] AST --> Check{Contains Playground?} Check -->|No| Clean[0 KB Extra Assets Emitted] Check -->|Yes| Assets[Inject docmd-playground.css & js] AST --> SourceCheck{Has src attribute?} SourceCheck -->|Yes| ReadFile[Resolve & Inline Local Script] SourceCheck -->|No| ParseFence[Parse Inner Code Fence] ReadFile -->|Missing File| WarnBlock[Emit Non-Breaking Warning Box] ReadFile -->|Success| Container[Generate Playground Container HTML] ParseFence --> Container Container --> Browser[Client Browser Runtime] Browser --> Exec[Sandbox Execution & Console Proxy] Browser --> RT[docmd-runtime Reactivity docmd.var]

1. Build-Time AST Interception

During the static site build:

  • Container Hook: Registers a custom rule on markdown-it-container targeting the playground keyword.
  • Code Fence Hook: Inspects code block language identifiers for playground or live flags (e.g. ```js playground).
  • Asset Flagging: When any playground container or fence is detected on a page, docmd flags 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="./...":

  • docmd resolves 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, and console.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.docmd and 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.
Security Isolation Model
  • 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" without allow-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:

js Active Sourced Script

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:

html Interactive Notification Card

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:

js Client Metrics Aggregator

Container & Plugin Cross-Reference