Die docmd-Version 0.7.5 kombiniert einen Sicherheitsfix mit bedeutenden i18n-Optimierungen. Sie beseitigt die vorgelagerte uuid-Schwachstelle aus dem Mermaid-Plugin, fügt mehrschichtige Absicherungen für den Sprachumschalter hinzu und führt ein Build-Zeit-Seitenmanifest ein, das alle Laufzeit-Netzwerkprüfungen durch sofortige lokale Abfragen ersetzt.
🛡️ Sicherheit
Mermaid-Plugin — Korrektur des Abhängigkeitsbaums
Das Paket @docmd/plugin-mermaid deklarierte mermaid zuvor als Produktions-dependency. Dies führte dazu, dass die verwundbare transitive Unterabhängigkeit uuid@<14.0.0 in jedem node_modules-Verzeichnis des Verbrauchers installiert wurde, obwohl das Paket diese zur Laufzeit nie verwendet.
Ursache: Die Mermaid-Bibliothek wird zur Laufzeit ausschließlich über ein CDN im Browser geladen. Das npm-Paket mermaid wurde nur während der Entwicklung für die TypeScript-Typprüfung und den esbuild-Bundling-Schritt benötigt. Es war fälschlicherweise als Produktionsabhängigkeit kategorisiert.
Lösung: mermaid wurde in @docmd/plugin-mermaid von dependencies nach devDependencies verschoben. Das veröffentlichte Paket wird nun mit null Produktionsabhängigkeiten ausgeliefert, sodass mermaid und seine verwundbare uuid-Unterabhängigkeit für Endbenutzer nie installiert werden.
npm audit/pnpm auditmeldet jetzt 0 Schwachstellen für Projekte, die@docmd/plugin-mermaidverwenden.- Keine funktionalen Änderungen — die Mermaid-Rendering-Pipeline ist vollständig unbeeinträchtigt.
🌐 i18n — Absicherung der Sprachumschaltung
Wenn bisher eine Locale in i18n.locales deklariert war, aber das zugehörige Quellverzeichnis (z. B. docs/hi/) nicht existierte, wurde sie in der Sprachumschaltung dennoch als klickbar dargestellt — was beim Auswählen zu einem 404-Fehler führte.
Lösung: Die Engine prüft Locale-Verzeichnisse jetzt zur Build-Zeit vorab. Locales ohne Quellverzeichnis werden in der Sprachumschaltung automatisch mit einem N/A-Badge, dem Attribut aria-disabled und einem nicht klickbaren Zustand deaktiviert.
- Build-Zeit-Erkennung: Die Engine prüft vor dem Rendern, welche Locale-Verzeichnisse tatsächlich existieren.
- Template-Deaktivierung: Nicht verfügbare Locales erscheinen ausgegraut mit einem „N/A"-Badge und
href="#". - Client-seitige Absicherung: Das Klicken auf eine deaktivierte Locale löst keine Navigation aus — kein 404.
- Verketteter Fallback: Wenn eine Locale verfügbar ist, aber eine bestimmte Seite fehlt, greift die Engine auf die Version der Standardsprache zurück und zeigt einen lokalisierten Warnhinweis an.
⚡ i18n — Build-Zeit-Seitenmanifest
Bisher verwendete der Sprachumschalter fetch(url, { method: 'HEAD' }), um zu prüfen, ob eine Seite in der Zielsprache existiert. Dies verursachte Latenz, funktionierte bei einigen CDNs nicht und war offline nicht verfügbar.
Lösung: Die Engine generiert jetzt ein Seitenmanifest zur Build-Zeit — eine kleine JS-Datei (docmd-i18n-manifest.js), die jede Locale ihren verfügbaren Seitenpfaden zuordnet. Der Client-seitige Umschalter liest dieses Manifest synchron.
- Null Netzwerkanfragen: Die Seitenexistenz wird lokal aus dem Manifest geprüft — keine HEAD-Abfragen.
- Funktioniert offline: Das Manifest wird mit den Site-Assets ausgeliefert.
- CDN-agnostisch: Keine Abhängigkeit davon, wie der Hosting-Anbieter HEAD-Anfragen behandelt.
- Graceful Degradation: Falls das Manifest nicht geladen werden kann, fällt der Umschalter automatisch auf HEAD-Abfragen zurück.
Wenn i18n aktiviert ist, muss jede Locale ein eigenes Unterverzeichnis unter dem Quellverzeichnis haben (z. B. docs/en/, docs/hi/). Das Verzeichnis der Standardsprache ist als Fallback-Quelle für teilweise übersetzte Locales erforderlich.
i18n-Absicherung — docmd im Vergleich
| Fähigkeit | docmd | VitePress | Docusaurus | Starlight |
|---|---|---|---|---|
| Seitenweiser Fallback auf Standardsprache | ✅ | ❌ (404) | ❌ (404) | ✅ |
| Lokalisierter „nicht übersetzt"-Hinweis | ✅ | ❌ | ❌ | ✅ |
| Fehlende Locales automatisch deaktivieren | ✅ | ❌ | ❌ | ❌ |
| Client-seitige Navigationsabsicherung | ✅ | ❌ | ❌ | ❌ |
| Versionierung + i18n kombiniert | ✅ | ❌ | ❌ | ❌ |
| Alte Versionen ohne Locale-Verzeichnisse | ✅ | N/A | N/A | N/A |
| RTL-Richtungsunterstützung | ✅ | ✅ | ✅ | ✅ |
| Zero-Config (ohne React/Vue-Komponenten) | ✅ | Teilweise | ❌ | ✅ |
VitePress und Docusaurus liefern 404-Fehler, wenn eine Seite in einer nicht-standardmäßigen Locale fehlt — was serverseitige Redirects oder benutzerdefinierte Komponenten erfordert. Starlight (Astro) bietet einen seitenweisen Fallback mit einem Übersetzungshinweis, ähnlich wie docmd — deaktiviert aber fehlende Locale-Verzeichnisse nicht automatisch und schützt nicht vor client-seitiger Navigation zu nicht vorhandenen Locales.
Migrationsleitfaden
Für Endbenutzer: Aktualisieren Sie auf den neuesten Patch mit npm update @docmd/plugin-mermaid oder pnpm update @docmd/plugin-mermaid. Es sind keine Konfigurationsänderungen erforderlich.