Playground-Plugin
Das @docmd/plugin-playground-Plugin bringt interaktive, ausführbare Codeblöcke und Live-Komponentenvorschauen direkt auf Ihre docmd-Website. Es ermöglicht Dokumentationsautoren, in sich geschlossene JavaScript-Ausführungen, Live-HTML/CSS-Komponenten und aktive Skriptdateien aus ihrem Repository einzubinden – ohne schwergewichtige Abhängigkeiten wie Monaco oder React.
Ab v0.9.9 wird @docmd/plugin-playground standardmäßig mit @docmd/core ausgeliefert und ist standardmäßig aktiviert. Dank des bedingten Asset-Ladens von docmd laden Seiten ohne Playground-Blöcke 0 KB zusätzliche Assets.
Hauptmerkmale
Verwenden Sie ```js playground oder ::: playground, um sofort eine interaktive Sandbox bereitzustellen.
Verlinken Sie Quellskripte direkt über ::: playground src="./snippets/demo.js" /:::, um Dokumentationsbeispiele synchron mit dem Projektcode zu halten.
Fängt console.log(), console.info(), console.warn() und console.error() in Echtzeit ab und formatiert Rückgabewerte übersichtlich.
Rendert interaktive UI-Komponenten in einem isolierten Vorschaufenster mit einfacher Umschaltung zwischen Konsole und Vorschau.
Direkter Zugriff auf die window.docmd-Laufzeitumgebung und reaktive Variablen über docmd.var.get() und docmd.var.set().
Interaktive Reiter in der Symbolleiste erlauben nahtloses Wechseln zwischen Live-Komponentenvorschau und Quellcode in einer sauberen Einzelfeld-Ansicht (tabs).
Fehlende Skripte erzeugen ein unaufdringliches Warnbanner mit Fallback-Code; Laufzeitfehler werden strukturiert in der Konsole gemeldet.
Reines Standard-JavaScript und CSS (< 10 KB Gesamtgröße) mit Tastaturkürzeln (Cmd+Enter / Ctrl+Enter zum Ausführen, Tab für Einrückung).
Plugin-Konfiguration
Da @docmd/plugin-playground ein Kern-Plugin ist, ist keine Konfiguration erforderlich. Globale Standardwerte können in docmd.config.json angepasst oder deaktiviert werden:
{
"plugins": {
"playground": {
"enabled": true,
"theme": "default",
"defaultLayout": "split"
}
}
}
Konfigurationsoptionen
| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
enabled |
boolean |
true |
Aktiviert oder deaktiviert das Playground-Rendering global. |
theme |
string |
"default" |
Farbschema passend zum aktiven docmd-Layout (default, dark, light). |
defaultLayout |
string |
"split" |
Standardanordnung (split für nebeneinander oder stacked für untereinander). |
Um die clientseitige Codeausführung auf der gesamten Website zu deaktivieren, setzen Sie "playground": false unter "plugins" in docmd.config.json. Alle Playground-Blöcke werden dann als standardmäßige Syntax-Codeblöcke dargestellt.
Technische Architektur & Interna
Das Playground-Plugin basiert auf einer schlanken, abhängigkeitsfreien Architektur:
1. Build-Zeit-AST-Verarbeitung
- Container- & Fence-Hooks: Registriert Verarbeitungsregeln für
playgroundinmarkdown-it. - Bedingte Asset-Einbindung: Nur Seiten mit Playground-Elementen binden die zugehörigen Skripte und Stylesheets ein.
2. Skriptauflösung mit src
- Löst Pfade relativ zum aktuellen Dokument oder Projektverzeichnis auf.
- Fehlende Dateien führen nicht zum Build-Abbruch, sondern erzeugen strukturierte Warnhinweise (
.docmd-playground-missing-alert).
3. Ausführungssandbox
- Fängt Konsolenaufrufe (
log,info,warn,error) ab und leitet sie formatiert in das Ausgabefenster weiter. - Direkte Integration mit der
docmd-runtime(docmd.var.get(),docmd.var.set()).
- Reine Client-Ausführung: Keine Server-Ausführung oder Backend-Angriffsfläche; jeglicher Code läuft im Browser des Besuchers.
- Iframe-Sandboxing: HTML-Vorschauen laufen in einem isolierten Iframe mit
sandbox="allow-scripts allow-modals allow-forms"ohneallow-same-origin, wodurch der Zugriff auf Cookies, LocalStorage und DOM der Dokumentationsseite blockiert wird. - Domain-Isolation: Für den Produktivbetrieb wird empfohlen, Dokumentationen auf einer eigenständigen Subdomain (z. B.
docs.example.com) bereitzustellen.
Skriptbasierte Beispiele & Workflows
Skript-Beispiel 1: Lokale Skripte einbinden mit src
::: playground src="./snippets/demo.js" title="Eingebundenes Skript" icon:cpu live /:::
Skript-Beispiel 2: Interaktive HTML- & CSS-Komponentenvorschau
Playgrounds rendern HTML- und CSS-Komponenten direkt in der Browser-Sandbox. Leser sehen die gerenderte Oberfläche in der Play-Ansicht und können jederzeit in die Code-Ansicht wechseln:
::: playground title="Interaktive Benachrichtigungskarte" 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;">Echtzeit-Benachrichtigung</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;">
Wechseln Sie in der oberen Symbolleiste zwischen <strong>Play</strong> und <strong>Code</strong>, um den Quellcode zu prüfen oder anzupassen.
</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('Aktion erfolgreich ausgelöst!')">
Aktion ausführen
</button>
</div>
```
:::
Live gerenderte Komponente:
Skript-Beispiel 3: JavaScript-Ausführung mit Konsolenausgabe
Führen Sie JavaScript-Skripte in einer geschützten Sandbox aus mit vollständiger Erfassung von console.log, info und Rückgabewerten:
Verwandte Dokumentation
- Playground-Container-Dokumentation: Vollständige Container-Syntax, Reiter, Layout-Optionen und interaktive Beispiele.
- Variablen & Personalisierung: Integration mit der
docmd-runtimefür clientseitige Reaktivität. - Container-Übersicht: Übersicht aller nativen Container in
docmd.