Playground

The ::: playground container turns static code examples into interactive, self-contained sandboxes. Readers can edit code in place, execute it with a single click or keyboard shortcut, inspect structured console outputs, toggle between live component outputs and underlying code, and preview live HTML/CSS components.

Zero-Config Architecture

The playground runtime is built using pure vanilla JavaScript and CSS, requiring no heavyweight frameworks. Pages that do not use playgrounds load zero extra bytes.

Container Syntax

# Standard Block Container
::: playground [title:"Toolbar Title"] [icon:icon_name] [live] [view:"code"|"live"] [tab:"preview"|"console"]
// JavaScript or HTML/CSS code snippet
::: /playground # Explicit container closer

# Self-Closing Sourced Script
::: playground src="./path/to/script.js" [title:"Toolbar Title"] [icon:icon_name] [live] /:::

# Shorthand Fenced Code Block
```js playground [title:"Toolbar Title"] [icon:icon_name] [live]
// JavaScript code snippet
```

Features & Supported Attributes

Parameter / Attribute Type Default Description
Title "String" | title:"..." Derived or "Playground" Toolbar heading label (positional 1st parameter or title:"...").
Source File src:PATH | file:PATH None Relative path to an external script file to inline into the playground editor.
Iconography icon:NAME "play" Optional. Lucide icon name rendered next to the title (e.g. icon:code, icon:cpu, icon:layout).
Language lang:LANG Derived ("js") Explicit language override (js, html, css). Inferred from file extensions or inner code fences.
Auto-Execution live false When present, executes the code automatically when the page loads.
Initial View view:"code" | view:"live" "live" Active initial view mode ("live" for output/preview or "code" to open directly in the editor).
Output Sub-Tab tab:"preview" | tab:"console" "console" or "preview" Active output sub-tab to display ("preview" or "console"). Bare preview flag is also supported.
No-Code Mode nocode false When present (or code:false), hides the “Code” button from the header switcher, presenting only the Live preview.
Read-Only readonly false Locks the code editor against user editing while allowing code execution.
Layout layout:"stacked" | "split" "stacked" Sets the layout presentation: unified single-panel view with Play/Code switcher by default, or "split" for side-by-side.
Closing Tags ::: /playground, /:::, ::: Standard closing Supports explicit closing tag ::: /playground, self-closing /:::, or generic :::.
Security Notice & Script Execution

All playground code runs entirely client-side inside the reader’s browser session. HTML previews execute inside a sandboxed iframe with an opaque origin (null), preventing access to parent DOM or cookies. When using live auto-execution, ensure code snippets originate from trusted documentation sources.

Usage Examples

Interactive JavaScript Runner

Standard block playground demonstrating console.log, console.info, console.warn, and expression returns:

::: playground title="JavaScript Console & Return Demo" icon:code live
```js
console.log("Hello from docmd!");
console.info("Status payload:", { status: "active", version: "0.9.9" });
console.warn("Notice: demo warning");
return "Execution completed successfully";
```
::: /playground
js JavaScript Console & Return Demo

Live HTML Component Preview

When the playground language is set to html (or lang:html), the playground automatically selects the Preview panel and renders the HTML/CSS inside a sandboxed frame:

::: playground title="Interactive Component Preview" icon:layout live
```html
<div style="padding: 18px; border-radius: 10px; background: #0f172a; color: #38bdf8; font-family: system-ui, sans-serif; border: 1px solid #1e293b;">
  <div style="display:flex; align-items:center; gap:8px; margin-bottom:8px;">
    <span style="display:inline-block; width:10px; height:10px; border-radius:50%; background:#10b981;"></span>
    <strong style="color:#f8fafc; font-size:14px;">Instant Component Preview</strong>
  </div>
  <p style="margin:0 0 12px 0; font-size:13px; color:#94a3b8; line-height:1.5;">
    Switch between the <strong>Play</strong> live rendering and <strong>Code</strong> view using the toolbar switcher.
  </p>
  <button style="padding:6px 14px; background:#0284c7; color:#fff; border:none; border-radius:6px; font-size:12px; font-weight:600; cursor:pointer;" onclick="console.log('Action triggered from component preview!')">
    Trigger Console Log
  </button>
</div>
```
::: /playground
html Interactive Component Preview

Reactive Variables & docmd Runtime Integration

Playgrounds have access to the global window.docmd runtime object and reactive variables:

::: playground title="Reactive Variable Explorer" icon:sparkles live
```js
const buildYear = docmd.var.get("docmd.buildYear");
const siteTitle = docmd.var.get("site.title");

console.log("Site Title:", siteTitle);
console.log("Build Year:", buildYear);

// Modify a client-side reactive variable
docmd.var.set("user.plan", "Enterprise");
console.info("Updated user plan to:", docmd.var.get("user.plan"));
return `Current Year: ${buildYear}`;
```
::: /playground
js Reactive Variable Explorer

Code-First Initial View (view:"code")

Configure the playground to open directly in the code editor on page load while keeping the instant “Play” toggle accessible:

::: playground view:"code" title="Factorial Algorithm (Code First)" icon:code live
```js
// Compute factorial recursively
function factorial(n) {
  if (n <= 1) return 1;
  return n * factorial(n - 1);
}

const num = 5;
const result = factorial(num);
console.log(`Factorial of ${num} is:`, result);
return result;
```
::: /playground
js Factorial Algorithm (Code First)

Active Sourced Script (src)

Link directly to an active script in your repository using the src attribute:

::: playground src="./snippets/counter.js" title="Active Sourced Script" icon:cpu live /:::
js Active Sourced Script
Continuous Code Synchronisation

When using src="./path/to/file", docmd resolves the file at build time relative to your documentation page or workspace root. When your codebase updates, your documentation examples update automatically on the next build without manual edits. If a source file is missing or relocated, docmd displays a graceful warning banner without failing the build.

Shorthand Fenced Code Block

For quick snippets without container block nesting, append playground directly to any standard Markdown code fence:

```js playground title="Quick Fibonacci Runner" icon:zap
function fib(n) {
  return n <= 1 ? n : fib(n - 1) + fib(n - 2);
}

console.log("Fib(10) =", fib(10));
return fib(10);
```
js Quick Fibonacci Runner

Keyboard Shortcuts

The playground editor provides standard IDE keyboard shortcuts for rapid iteration:

Shortcut Description
Cmd + Enter / Ctrl + Enter Run the active code block.
Tab Inserts a 2-space indentation instead of shifting browser focus.
Shift + Tab Un-indents the current line or selection.

For deep technical details on AST parsing hooks, build-time script resolution, graceful error handling mechanics, and global plugin configuration options, see the Playground Plugin Architecture & Technical Reference.