Plugins sind der primäre Erweiterungsmechanismus für docmd. Sie ermöglichen das Einfügen von benutzerdefiniertem HTML, das Ändern der Markdown-Parslogik, das Einschleusen von Build-Zeit-Daten vor dem Template-Rendering und die Automatisierung von Post-Build-Aufgaben. Dieser Leitfaden beschreibt die Plugin-API und Best Practices für die Erstellung wiederverwendbarer Komponenten.

Plugin-Deskriptor

Jedes Plugin sollte einen plugin-Deskriptor exportieren, der seine Identität und Fähigkeiten deklariert. Dies ermöglicht der Engine, Fähigkeitsgrenzen beim Laden zu validieren, zu isolieren und durchzusetzen.

export default {
  plugin: {
    name: 'my-analytics',
    version: '1.0.0',
    capabilities: ['head', 'body', 'post-build']
  },

  generateScripts: (config, opts) => { ... },
  onPostBuild: async (ctx) => { ... }
};

Hinweis: Der Deskriptor ist derzeit optional (Soft-Deprecation-Warnung). Er wird ab 0.8.0 erforderlich sein.

Kern-Fähigkeiten

Das capabilities-Array bestimmt, welche Hooks Ihr Plugin verwenden darf.

Legacy-Plugins ohne Deskriptor erhalten vollen Zugriff auf alle Hooks, sodass während der Übergangsphase nichts abbricht.

Plugin-API-Referenz

Ein docmd-Plugin ist ein Standard-JavaScript-Objekt (oder ein Modul, das eines als Standard exportiert), das einen oder mehrere der folgenden Hooks implementiert.

Ein lokales Plugin erstellen

Ein Plugin zu erstellen ist so einfach wie das Definieren einer JavaScript-Datei. Zum Beispiel my-plugin.js:

// my-plugin.js
import path from 'path';

export default {
  plugin: {
    name: 'my-plugin',
    version: '1.0.0',
    capabilities: ['head', 'post-build']
  },

  markdownSetup: (md, options) => {
    // Beispiel: Regel hinzufügen oder markdown-it-Plugin verwenden
  },

  generateMetaTags: async (config, page, relativePathToRoot) => {
    return `<meta name="x-build-id" content="${config._buildHash}">`;
  },

  onPostBuild: async ({ config, pages, outputDir, log, options }) => {
    log(`Benutzerdefiniertes Plugin: ${pages.length} Seiten überprüft.`);
  }
};

Verweisen Sie in Ihrer docmd.config.js über den vollständigen Paketnamen auf Ihr Plugin:

import { defineConfig } from '@docmd/core';

export default defineConfig({
  plugins: {
    'my-awesome-plugin': {
      // Ihre benutzerdefinierten Optionen hier
    }
  }
});

Hinweis: Kurzformen (z.B. math, search) sind ausschließlich für offizielle @docmd/plugin-*-Pakete reserviert. Drittanbieter-Plugins müssen immer mit ihrem vollständigen npm-Paketnamen referenziert werden.

Plugin-Isolierung

Jeder Hook-Aufruf ist in eine try/catch-Grenze eingebettet. Ein defektes Plugin kann den Build nicht zum Absturz bringen oder andere Plugins stören. Fehler werden protokolliert und am Ende des Builds in einer Zusammenfassung gesammelt.

Lebenszyklus-Hooks

docmd bietet tiefe Integrations-Hooks, die es Plugins ermöglichen, Konfiguration, Rohquellen und Seitendaten während der gesamten Build-Pipeline zu manipulieren.

onBeforeRender und PageContext

Der onBeforeRender-Hook ist der richtige Ort für Plugins, die Build-Zeit-Daten aus der Quelldatei einschleusen müssen — Datei-Metadaten lesen, benutzerdefinierte Frontmatter-Felder berechnen oder Daten aus externen Quellen laden.

interface PageContext {
  sourcePath: string;           // Absoluter Pfad zur .md-Quelldatei. Immer gesetzt.
  frontmatter: Record<string, any>; // Veränderbar — Änderungen in der Template-Ausgabe widergespiegelt
  html: string;                 // Veränderbar — gerenderter Markdown-Body
  localeId?: string;
  versionId?: string;
  relativePathToRoot?: string;
}

export default {
  plugin: {
    name: 'my-metadata-plugin',
    version: '1.0.0',
    capabilities: ['build']
  },

  onBeforeRender: async (page) => {
    // sourcePath ist immer verfügbar — kein Raten oder Pfadkonstruktion nötig
    const stats = fs.statSync(page.sourcePath);
    page.frontmatter.wordCount = page.html.split(/\s+/).length;
    page.frontmatter.fileSize = stats.size;
  }
};

Vertiefung: Asset-Einbindung

Der getAssets()-Hook ermöglicht es Ihrem Plugin, clientseitige Logik sicher zu bündeln.

getAssets: (options) => {
  return [
    {
      url: 'https://cdn.example.com/lib.js',
      type: 'js',
      location: 'head'
    },
    {
      src: path.join(__dirname, 'plugin-init.js'),
      dest: 'assets/js/plugin-init.js',
      type: 'js',
      location: 'body'
    }
  ];
}

Plugins übersetzen (i18n)

Plugins, die clientseitige UI rendern, sollten übersetzbare Strings über den translations(localeId)-Hook bereitstellen.

export default {
  plugin: {
    name: 'my-plugin',
    version: '1.0.0',
    capabilities: ['translations', 'body']
  },

  translations: (localeId) => {
    try {
      const p = path.join(__dirname, 'i18n', `${localeId}.json`);
      return JSON.parse(fs.readFileSync(p, 'utf8'));
    } catch { }
    try {
      const p = path.join(__dirname, 'i18n', 'en.json');
      return JSON.parse(fs.readFileSync(p, 'utf8'));
    } catch { }
    return {};
  }
}

WebSocket-RPC-Aktionen

Plugins können Aktions-Handler und Event-Handler registrieren, die auf dem Dev-Server laufen und über die window.docmd-API vom Browser aufrufbar sind.

export default {
  plugin: {
    name: 'my-live-plugin',
    version: '1.0.0',
    capabilities: ['actions', 'events']
  },

  actions: {
    'my-plugin:save-note': async (payload, ctx) => {
      const content = await ctx.readFile(payload.file);
      const updated = content + '\n\n> ' + payload.note;
      await ctx.writeFile(payload.file, updated);
      return { saved: true };
    }
  },

  events: {
    'my-plugin:page-viewed': (data, ctx) => {
      console.log(`Seite aufgerufen: ${data.path}`);
    }
  }
};

Das ctx-Objekt (ActionContext) bietet:

Best Practices

1. Fähigkeiten deklarieren: Exportieren Sie immer einen plugin-Deskriptor mit Ihren deklarierten Fähigkeiten. Ab 0.8.0 wird dies erforderlich sein.
2. onBeforeRender für Dateneinfügung verwenden: Wenn Ihr Plugin die Quelldatei liest oder Frontmatter-Felder berechnet, verwenden Sie onBeforeRender — nicht generateMetaTags. sourcePath ist im PageContext immer verfügbar.
3. Async/Await: Verwenden Sie immer async-Funktionen für onPostBuild, onBeforeRender und Aktions-Handler.
4. Zustandslosigkeit: Vermeiden Sie die Beibehaltung von Zustand im Plugin-Objekt, da docmd Plugins während Entwicklungs-Rebuilds neu initialisieren kann.
5. Namenskonvention: Für Community-Plugins, stellen Sie docmd-plugin- voran (z.B. docmd-plugin-analytics).
6. Aktions-Namensräume: Stellen Sie Ihren Plugin-Namen voran (z.B. my-plugin:save-note) um Kollisionen zu vermeiden.
7. Aktionsvalidierung: Definieren Sie immer ein explizites Payload-Schema in Ihren Aktionen.
8. Logging: Verwenden Sie den bereitgestellten log()-Helfer in onPostBuild.