Markdown Preview (BDE)

Eigenständige Markdown-Vorschau für VS Code. Bewusst minimal, vollständig offline lauffähig, ohne Telemetrie und ohne externe Netzwerkaufrufe. Der Rendering-Pfad ist vollständig im Quelltext einsehbar und auditierbar.

Sicherheitsmodell

• Strikte Content-Security-Policy im Webview: default-src 'none', Skripte nur mit zufälligem Nonce, Styles und Schriften ausschließlich aus der Extension selbst.
• Rohes HTML standardmäßig deaktiviert (mdPreview.allowHtml = false). Markdown-Quelltext mit eingebettetem HTML wird literal escaped, nicht ausgeführt.
• Keine externen Ressourcen by default. Remote-Bilder (https) sind über mdPreview.allowRemoteImages schaltbar; bei false nur lokale Dateien und data:-URIs. Lokale Bild-Zugriffe sind durch localResourceRoots begrenzt.
• Mermaid wird offline gebündelt, nicht von einem CDN geladen. Diagramme werden mit securityLevel: 'strict' gerendert (sanitisierte Labels, keine HTML-Labels, keine Klick-Bindings).
• Vier Laufzeit-Abhängigkeiten, alle weit verbreitet und gut geprüft: markdown-it, highlight.js, markdown-it-task-lists, mermaid. Alles wird beim Build per esbuild gebündelt; im VSIX liegt kein node_modules.
• Keine Telemetrie, keine Analytics, keine Auto-Updates.

Funktionen

• GitHub-nahe, gut lesbare Darstellung, die sich an das aktive VS-Code-Theme anpasst (Hell / Dunkel / High Contrast über die --vscode-*-Variablen).
• Syntax-Highlighting via highlight.js, Theme-abhängiges Farbschema.
• Mermaid-Diagramme in ```mermaid-Blöcken, Theme-synchron (hell/dunkel), live aktualisiert beim Tippen.
• Tabellen, Aufgabenlisten (- [ ] / - [x]), Zitate, Codeblöcke.
• Anker-Links auf Überschriften über automatische, GitHub-ähnliche Slugs.
• Live-Aktualisierung beim Tippen (entprellt, ohne Scroll-Verlust) und beim Speichern. Inhalt wird per Nachricht ins Webview gereicht, nicht durch einen vollständigen Reload.
• Scroll-Synchronisation Editor → Vorschau (mdPreview.syncScroll).
• Relative Links auf andere Dateien öffnen das Ziel im Editor.
• Export nach HTML (in sich geschlossen) und nach PDF (über den Druckdialog des Browsers).

Export

• Als HTML exportieren erzeugt eine eigenständige .html-Datei: CSS inline, lokale Bilder als data:-URIs eingebettet, Mermaid-Diagramme als fertige SVGs. Die Datei ist portabel und braucht weder VS Code noch Internet. Ohne aktives VS-Code-Theme greifen die im CSS hinterlegten hellen Fallback-Farben.
• Als PDF exportieren (Druckdialog) erzeugt dieselbe HTML-Ausgabe in einer temporären Datei, öffnet sie im Standardbrowser und löst den Druckdialog aus. Dort „Als PDF speichern" wählen. Dieser Weg kommt ohne gebündeltes Chromium aus und hält die Extension klein und auditierbar. Ein eingebettetes @media print-Stylesheet sorgt für sauberen Umbruch (Code-Wrapping, Seitenumbrüche vor Überschriften und um Diagramme).

Mermaid-Diagramme werden für den Export im hellen Theme über das (ggf. kurz geöffnete) Vorschau-Webview zu SVG gerendert und dann in die Ausgabe eingebettet.

Befehle

Einstellungen

Sprachen

Die Extension ist zweisprachig (Englisch als Standard, Deutsch als Uebersetzung) und richtet sich nach der Anzeigesprache von VS Code. Statische Beitraege (Befehle, Einstellungen) werden ueber package.nls.json / package.nls.de.json uebersetzt, Laufzeit-Texte ueber vscode.l10n.t(...) mit Buendeln unter l10n/ (bundle.l10n.json als Quelle, bundle.l10n.de.json fuer Deutsch). Weitere Sprachen ergaenzt man durch zusaetzliche package.nls.<locale>.json- und l10n/bundle.l10n.<locale>.json-Dateien. Die englischen Strings im Quelltext und in package.nls.json sind der Fallback.

Build und Installation

Voraussetzung: Node.js (LTS) und npm.

npm install
npm run build          # erzeugt dist/extension.js und dist/webview.js

Zwei Bundles entstehen: dist/extension.js (Extension-Host) und dist/webview.js (Webview, inkl. gebündeltem mermaid — daher mehrere hundert KB).

Debuggen: Projekt in VS Code öffnen und F5 (Extension-Development-Host).

Paket bauen und installieren:

npm run package        # erzeugt md-preview-0.2.0.vsix
code --install-extension md-preview-0.2.0.vsix

Projektstruktur

md-preview/
├── package.json              Manifest (Befehle, Menüs, Settings)
├── esbuild.js                baut beide Bundles
├── tsconfig.json             nur Typprüfung (npm run typecheck)
├── src/
│   ├── extension.ts          Aktivierung, Webview, CSP, Scroll-Sync, Export
│   ├── markdownRenderer.ts    markdown-it, Highlighting, Slugs, Mermaid-Fence
│   └── webview/
│       └── main.ts            Webview-Client: Updates, Links, Mermaid (live+Export)
└── media/
    ├── preview.css           Lese-Styles inkl. Mermaid, an VS-Code-Theme gekoppelt
    └── highlight.css         highlight.js-Theme (Hell/Dunkel/HC)

dist/ wird beim Build erzeugt und ist nicht eingecheckt.

Hinweise und mögliche Anpassungen

• CSP und Mermaid: Wenn Mermaid (oder rohes HTML) aktiv ist, enthält style-src zusätzlich 'unsafe-inline', weil Mermaid Inline-Styles in seine SVGs schreibt. Skripte bleiben strikt nonce-gebunden. Sollte ein Diagramm ausnahmsweise nicht erscheinen, lohnt ein Blick in die Webview-DevTools-Konsole (Befehl „Developer: Open Webview Developer Tools"): meldet sie einen CSP-Verstoß zu eval, in buildShellHtml (src/extension.ts) bei script-src ein 'unsafe-eval' ergänzen.
• Bundle-Größe: Mermaid ist groß. mdPreview.mermaid = false schaltet das Rendering ab, verkleinert aber das Bundle nicht (es ist Teil von webview.js). Wer das Bundle ohne Mermaid will, entfernt den Import in src/webview/main.ts und baut neu.
• Echtes headless-PDF: Der PDF-Weg nutzt bewusst den Browser-Druckdialog statt eines gebündelten Chromium. Wer voll automatisiertes PDF braucht, kann in einem separaten Schritt z. B. Puppeteer auf die exportierte HTML ansetzen.

Bekannte Grenzen

• Scroll-Sync ist blockbasiert (data-line der obersten Blockebene), also annähernd, nicht pixelgenau.
• Die Vorschau ist an ihr Quelldokument gebunden; sie folgt nicht automatisch dem aktiven Editor.

Lizenz

Apache License 2.0 \u2013 siehe LICENSE und NOTICE. Gebuendelte Drittanbieter- Komponenten behalten ihre eigenen Lizenzen; siehe THIRD-PARTY-NOTICES.md.