Konfigurations- & Benutzerdefinierte Variablen

Konfigurations- & Benutzerdefinierte Variablen

Sie können benutzerdefinierte Variablen direkt in docmd.config.json definieren, aus externen JSON-Dateien oder JavaScript-Modulen laden und in Ihrer gesamten Dokumentation verwenden.

Variablen in docmd.config.json definieren

Fügen Sie Ihrer docmd.config.json einen variables-Block hinzu:

{
  "title": "Acme Cloud Dokumentation",
  "variables": {
    "companyName": "Acme Technologies",
    "supportEmail": "support@acme.com",
    "cloud": {
      "apiEndpoint": "https://api.acme.cloud/v2",
      "region": "eu-central-1",
      "maxInstances": 50
    }
  }
}

Zugriff in Markdown

Verschachtelte Eigenschaften werden mit gewohnter Punktnotation angesprochen:

Unser Support-Team erreichen Sie unter [{{ supportEmail }}](mailto:{{ supportEmail }}).

Alle Anfragen richten Sie an unseren Endpunkt:
```bash
curl -X GET {{ cloud.apiEndpoint }}/status \
  -H "X-Region: {{ cloud.region }}"
```

Während des Builds wird dies aufgelöst zu:

curl -X GET https://api.acme.cloud/v2/status \
  -H "X-Region: eu-central-1"

Zugriff auf Konfigurationsvariablen in Client-JavaScript & Playgrounds

Alle in docmd.config.json deklarierten Variablen werden automatisch in die Client-Laufzeit (window.__DOCMD_VARIABLES__) übertragen und stehen in Browser-Skripten, benutzerdefinierten Erweiterungen und interaktiven Playgrounds über window.docmd.var.get() zur Verfügung:

// In docmd.config.json definierte Variablen abfragen
const endpoint = window.docmd?.var?.get("cloud.apiEndpoint");
const region = window.docmd?.var?.get("cloud.region");
console.log(`Verbindung zu ${endpoint} in ${region}`);
1:1 Namenszuordnung

Variablenschlüssel stimmen exakt mit den Markdown-Namen überein. Wenn Sie {{ cloud.apiEndpoint }} in Markdown schreiben, verwenden Sie window.docmd.var.get("cloud.apiEndpoint") in JavaScript. Stellen Sie Benutzervariablen kein docmd. voran.

Variablen in Konfigurationsfeldern nutzen

docmd führt einen einheitlichen Variablen-Pass durch, bevor Layouts, Menüs und Fußzeilen gerendert werden.

Sie können integrierte Variablen wie {{ docmd.buildYear }} oder {{ docmd.version }} sowie eigene Werte direkt in Konfigurationsfeldern einsetzen:

{
  "title": "Acme Docs",
  "variables": {
    "companyName": "Acme Cloud Systems"
  },
  "footer": {
    "copyright": "Copyright © {{ docmd.buildYear }} {{ companyName }}. Alle Rechte vorbehalten."
  },
  "layout": {
    "banners": {
      "top": {
        "content": "**docmd v{{ docmd.version }} ist live!** — Region: {{ env.DEPLOY_REGION || 'global' }}."
      }
    }
  }
}
Der einheitliche Auflösungs-Zyklus
  1. Registrierung: Beim Start von docmd build registriert die VariableRegistry alle integrierten Variablen, Umgebungsvariablen und Konfigurationswerte.
  2. Konfigurations-Interpolation: docmd durchläuft rekursiv docmd.config.json und ersetzt alle {{ variable }}-Ausdrücke.
  3. Markdown-Rendering: Markdown-Prozessoren nutzen exakt denselben Registry-Bestand für die Seitengenerierung.
  4. Ergebnis: Sowohl Fußzeile als auch Markdown-Inhalte sind stets synchron ohne manuelle Dopplung.

Externe Variablen-Dateien

Für größere Projekte oder geteilte Teamspezifikationen können Sie "variables" auf externe JSON- oder JavaScript-Dateien verweisen:

Externe JSON-Datei
Dynamisches JavaScript-Modul

Verweisen Sie auf eine JSON-Datei in Ihrem Repository:

{
  "variables": "./data/variables.json"
}

Inhalt von ./data/variables.json:

{
  "auth": {
    "oauthUrl": "https://auth.acme.com/oauth2/token",
    "clientId": "acme-portal-production"
  },
  "limits": {
    "rateLimitPerMin": 1200
  }
}

Verweisen Sie auf eine JavaScript-Datei für dynamische Berechnungen:

{
  "variables": "./data/variables.js"
}

Inhalt von ./data/variables.js:

module.exports = {
  dynamicTimestamp: new Date().toLocaleDateString('de-DE'),
  sdkVersion: require('./package.json').version,
  activeServices: ['auth', 'billing', 'analytics']
};
Best Practice: Zentrale Datenquelle

Über ein JavaScript-Modul können Sie Versionsnummern direkt aus der package.json importieren, sodass die Dokumentation stets mit Code-Releases übereinstimmt.