docs.json-Referenz

Die Datei docs.json ist die zentrale Konfiguration für Ihre Jamdesk-Dokumentationswebsite.

Erforderliche Felder

name

Typ: string (erforderlich)

Der Name Ihrer Dokumentationswebsite. Wird im Header und im Browser-Tab angezeigt.

{ "name": "Acme API Docs" }

theme

Typ: "jam" | "nebula" | "pulsar" | "halo" (erforderlich)

colors

Typ: object (erforderlich)

{
  "colors": {
    "primary": "#635BFF",
    "light": "#7C75FF",
    "dark": "#4F46E5"
  }
}

Branding

favicon

Typ: string oder object

Pfad zu Ihrer Favicon-Datei (SVG empfohlen). Geben Sie ein einzelnes Bild für beide Modi oder separate Varianten für light und dark an.

{ "favicon": "/images/favicon.svg" }

{
  "favicon": {
    "light": "/images/favicon.svg",
    "dark": "/images/favicon-dark.svg"
  }
}

logo

Typ: object

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp",
    "href": "https://yoursite.com"
  }
}

Typografie

fonts

Typ: object (optional)

Überschreiben Sie die Standardschrift des Themes für Fließtext und Überschriften. Jedes Theme enthält eine abgestimmte Standardschrift. Setzen Sie fonts nur, wenn Sie ein anderes Erscheinungsbild benötigen.

Verwenden Sie überall dieselbe Schriftart:

{
  "fonts": {
    "family": "Lora"
  }
}

Überschriften und Fließtext trennen:

{
  "fonts": {
    "heading": { "family": "Space Grotesk" },
    "body": { "family": "Inter" }
  }
}

Sowohl heading als auch body akzeptieren dieselben Felder. Siehe Theming → Typography für Hinweise zur Auswahl von Schriften.

Erscheinungsbild

appearance

Typ: object (optional)

Steuern Sie das standardmäßige Verhalten des Dark Mode Ihrer Website.

{
  "appearance": {
    "default": "dark",
    "strict": true
  }
}

Siehe Theming → Dark Mode, um zu erfahren, wie sich der Umschalter verhält.

Seitenmetadaten

metadata

Typ: object (optional)

Steuern Sie die auf jeder Dokumentationsseite angezeigten Seitenmetadaten.

{
  "metadata": {
    "timestamp": true
  }
}

Das Datum wird auf Ihrer veröffentlichten Website und in jamdesk dev angezeigt. Es entspricht dem letzten Commit, der die Datei der jeweiligen Seite geändert hat. Seiten, die Sie nicht bearbeitet haben, behalten ihr ursprüngliches Datum.

Banner

banner

Zeigen Sie oben auf jeder Seite über dem Header eine seitenweite Ankündigungsleiste in voller Breite und in der Akzentfarbe Ihres Themes an. Verwenden Sie sie für Veröffentlichungen, Migrationen, Wartungsfenster oder Nachrichten, die jeder Besucher sehen soll.

{
  "banner": {
    "content": "🎉 Version 2.0 is live! Read the [changelog](/changelog).",
    "dismissible": true
  }
}

Der Banner wird auf Ihrer veröffentlichten Website und in jamdesk dev angezeigt. Er wird global konfiguriert (ein Banner für die gesamte Website); Banner pro Tab und pro Sprache werden derzeit nicht unterstützt.

OpenAPI

api.openapi

Typ: string | string[]

Liste der OpenAPI-3.x-Spezifikationsdateien, die Jamdesk validieren und für Endpoint-Seiten verwenden soll. Verwenden Sie Pfade relativ zu Ihrer docs.json.

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Nach der Konfiguration können Sie Endpoint-Seiten erzeugen, indem Sie im Frontmatter einer Seite ein Feld openapi hinzufügen:

---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---

Wenn Sie nur eine Spezifikation aufgelistet haben, können Sie auch das Kurzformat verwenden:

---
title: Create Ticket
openapi: POST /tickets
---

Siehe OpenAPI Example für eine Live-Endpoint-Seite und Directory Structure zur Ablage von Dateien.

Wenn Ihre Website mehrsprachig ist, legen Sie neben jeder Quellspezifikation eine Datei im Format <spec>.<lang>.<ext> ab (z. B. openapi/api.fr.yaml); Jamdesk stellt sie unter den URLs der jeweiligen Sprache bereit. Siehe Translating OpenAPI Specs.

navigation openapi (generierte Seiten)

Typ: object

Fügen Sie einem Navigationstab ein openapi-Objekt hinzu und setzen Sie generate: true; Jamdesk erstellt dann zur Build-Zeit eine Endpoint-Seite pro Operation dieser Spezifikation sowie die Seitenleistengruppen, die sie aufnehmen. Kein redaktioneller Aufwand, keine Commits.

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Generierte Seiten liegen unter dem eigenen Namen des Tabs in Slug-Form. Der Slug wird aus Methode und Pfad gebildet — der obige Tab legt POST /tickets unter /api-reference/post-tickets ab. Operationen werden nach ihrem ersten tag gruppiert; Spezifikationen ohne Tags verwenden ersatzweise das erste aussagekräftige Pfadsegment. /api/v1/auctions/{auctionId} landet somit unter Auctions. Titel stammen aus der Operations-summary, sofern die Spezifikation eine enthält, andernfalls aus Methode und Pfad. Eine Operation für eine einzelne Ressource erhält einen Titel im Singular (GET /users/{id} → „Get User“).

Eine festgeschriebene .mdx-Datei gewinnt immer bei einer Slug-Kollision. Sie können die Generierung daher schrittweise übernehmen: Aktivieren Sie sie und löschen Sie anschließend nach und nach Ihre manuell geschriebenen Endpoint-Seiten.

Wenn Sie später einen Pfad in Ihrer Spezifikation umbenennen, wird der generierte Slug entsprechend verschoben. Jamdesk führt eine Slug-Historie pro Operation und erzeugt bei jedem Build eine Weiterleitung von jeder früheren URL zur aktuellen URL. Eingehende Links und Lesezeichen bleiben dadurch erhalten. Ihre eigenen redirects und jede aktive Seite haben weiterhin Vorrang.

Aktuelle Einschränkungen. Die Generierung läuft nur für navigation.tabs auf oberster Ebene — nicht für Gruppen, Anker oder Tabs innerhalb von languages oder versions — und erzeugt nur Seiten für Ihre Standardsprache. Ein Schlüssel directory wird vom Schema akzeptiert, hat aber keinen Einfluss darauf, wo Seiten abgelegt werden.

api.mdx.server

Typ: string

Basis-URL für Codebeispiele auf Frontmatter-Seiten mit api: (der von MDX verfasste Typ, nicht Seiten mit openapi:, die ihre Server aus der Spezifikation übernehmen).

{
  "api": {
    "mdx": {
      "server": "https://api.example.com"
    }
  }
}

api.examples.languages

Typ: string[] Standard: ["curl", "python", "javascript"]

Wählen Sie die Programmiersprachen aus, die in automatisch generierten API-Codebeispielen auf openapi:-Seiten erscheinen. Die Reihenfolge des Arrays bestimmt die Reihenfolge der Tab-Anzeige; standardmäßig ist die erste Sprache ausgewählt.

Unterstützte Werte: curl, bash, python, javascript, go, ruby, csharp, java, rust, php

{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}

{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}

api.examples.defaults

Typ: "required" | "all" Standard: "all"

Steuern Sie, welche Parameter in automatisch generierten Codebeispielen erscheinen.

{
  "api": {
    "examples": {
      "defaults": "required"
    }
  }
}

api.examples.prefill

Typ: boolean Standard: false

Wenn true, füllt der API Playground Parameterfelder mit example-Werten aus Ihrer OpenAPI-Spezifikation vorab aus.

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

api.playground.display

Typ: "interactive" | "simple" | "none" Standard: "interactive"

Steuert den API Playground auf Endpoint-Seiten. Auf jeder openapi:- und api:-Seite wird standardmäßig eine Schaltfläche „Try it“ angezeigt.

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Siehe API Playground zu Nutzungsdetails und seitenweisen Überschreibungen.

api.mdx.auth.method

Typ: "bearer" | "basic" | "key" | "cobo"

Authentifizierungsmethode für automatisch generierte Codebeispiele. Wenn diese Einstellung gesetzt ist, enthalten die Beispiele den passenden Authentifizierungs-Header.

{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
}

api.mdx.auth.name

Typ: string

Benutzerdefinierter Headername für schlüsselbasierte Authentifizierung. Wird nur verwendet, wenn api.mdx.auth.method auf "key" gesetzt ist.

{
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "X-API-Key"
      }
    }
  }
}

Navigation

tabsPosition

Typ: "top" | "left"

Steuert, wo Navigationstabs angezeigt werden.

Der Standardwert hängt von Ihrem Theme ab:

{ "tabsPosition": "left" }

anchors

Typ: array

Externe Links, die auf allen Seiten oben in der Seitenleiste erscheinen.

{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
  ]
}

navigation (Struktur)

Typ: object

Die Navigationsstruktur Ihrer Dokumentation. Siehe Navigation für eine ausführliche Dokumentation.

Seiten können Zeichenfolgen sein (Titel werden automatisch aus dem Dateinamen erzeugt) oder Objekte mit einem benutzerdefinierten Titel:

"pages": [
  "introduction",
  { "page": "content/mdx-basics", "title": "MDX Basics" }
]

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Navigationsleiste und Fußzeile

navbar

Typ: object

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

footer

Typ: object

Konfigurieren Sie die Fußzeile der Seite mit sozialen Links und benutzerdefinierten Linkspalten.

{
  "footer": {
    "socials": {
      "github": "https://github.com/yourorg",
      "x": "https://x.com/yourhandle",
      "discord": "https://discord.gg/yourserver"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          { "label": "Blog", "href": "https://example.com/blog" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      }
    ]
  }
}

Unterstützte soziale Plattformen: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Styling

styling.latex

Typ: boolean

Aktivieren Sie das Rendern von LaTeX-Mathematik mit KaTeX. Bei Aktivierung können Sie $...$ für Inline-Mathematik und $$...$$ für Blockgleichungen verwenden.

{
  "styling": {
    "latex": true
  }
}

Siehe Math & LaTeX zu Nutzungsdetails.

styling.js

Typ: string | string[]

Benutzerdefinierte JavaScript-Datei(en), die auf jeder Seite eingebunden werden. Die Pfade sind relativ zu Ihrem Dokumentationsverzeichnis und müssen mit / beginnen.

{
  "styling": {
    "js": "/script.js"
  }
}

Übergeben Sie ein Array für mehrere Dateien:

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

Ohne dieses Feld erkennt Jamdesk .js-Dateien in Ihrem Projektstamm automatisch. Siehe Custom JavaScript für Details.

Suche

search

Typ: object (optional)

Passen Sie die Suchleiste der Dokumentation an. Die Suche funktioniert sofort; dieses Feld ist nur erforderlich, wenn Sie den Platzhaltertext ändern oder beliebte Seiten im leeren Zustand anzeigen möchten.

{
  "search": {
    "prompt": "Ask me anything…",
    "popularPages": [
      { "title": "Quick Start", "slug": "quickstart", "icon": "rocket" },
      { "title": "Authentication", "slug": "guides/authentication", "icon": "key" }
    ]
  }
}

Beliebte Seiten

Jeder Eintrag in popularPages akzeptiert:

Das Feld icon akzeptiert auch das vollständige Objekt { "name", "style", "library" }. Siehe Icon object form. Wenn popularPages nicht angegeben ist, zeigt Jamdesk standardmäßig Quick Start und Introduction an.

Chat

chat

Typ: object (optional)

Konfigurieren Sie den integrierten KI-Chat-Assistenten. Der Chat ist standardmäßig auf allen Websites aktiviert; dieses Feld benötigen Sie nur, um Einstiegsfragen anzupassen oder den Chat zu deaktivieren.

{
  "chat": {
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

Siehe AI Chat, um zu erfahren, wie der Chat funktioniert und was Besucher sehen.

Menü für KI-Aktionen

contextual

Typ: object (optional)

Konfigurieren Sie das Dropdown-Menü für KI-Aktionen, das auf jeder Seite erscheint. Es ist standardmäßig mit allen Optionen aktiviert; dieses Feld benötigen Sie nur, um die angezeigten Optionen anzupassen oder das Menü zu deaktivieren.

Integrierte Optionsschlüssel: copy, view, chatgpt, claude, perplexity, gemini, mcp, cursor, vscode

{
  "contextual": {
    "options": ["copy", "claude", "mcp", "cursor"]
  }
}

Fügen Sie neben integrierten Optionen benutzerdefinierte Optionen hinzu:

{
  "contextual": {
    "options": [
      "copy",
      "claude",
      {
        "title": "Ask on Discord",
        "description": "Get help from the community",
        "icon": "discord",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}

Siehe AI Actions Menu für die vollständige Liste der Optionen und das Format benutzerdefinierter Optionen.

Rechtschreibprüfung

spellcheck

Typ: object (optional)

Konfigurieren Sie den CLI-Befehl jamdesk spellcheck. Dieses Feld benötigen Sie nur, um projektspezifische Wörter zur Ignorierliste hinzuzufügen.

{
  "spellcheck": {
    "ignore": ["Acme", "kubectl", "Terraform"]
  }
}

Die CLI enthält mehr als 180 integrierte technische Begriffe (API, GraphQL, Kubernetes, React usw.) und ignoriert automatisch den Projektnamen aus dem Feld name. Fügen Sie nur projektspezifische Wörter hinzu.

Siehe CLI Overview: Spellcheck zu Nutzungsdetails und dem interaktiven Korrekturmodus.

Bilder

images.convertToWebp

Typ: boolean (optional, Standard false)

Aktivieren Sie die automatische WebP-Konvertierung von PNG- und JPG-Assets während der Builds. Konvertierte Dateien sind normalerweise 60–80 % kleiner als die Originale, ohne sichtbaren Qualitätsverlust. Verweise in Ihrem MDX, benutzerdefiniertem CSS, benutzerdefiniertem JS und in docs.json werden automatisch angepasst; Sie müssen keine Pfade ändern.

Favicons, og:image und twitter:image behalten ihr ursprüngliches Format. Nicht jeder Social-Crawler oder E-Mail-Client rendert WebP zuverlässig, und eine defekte Vorschaukarte ist schlechter als ein etwas größeres JPG.

{
  "images": {
    "convertToWebp": true
  }
}

Siehe Automatic Image Conversion dazu, was konvertiert wird, wie das Caching funktioniert und wie der Build-Fortschrittsindikator arbeitet.

Zugriffskontrolle

auth.password

Typ: object (optional)

Aktivieren Sie den Schutz Ihrer Website durch ein gemeinsames Passwort. Die Konfiguration ist deklarativ. Die eigentliche Passphrase legen Sie weiterhin im Dashboard fest, nachdem der nächste Build ausgeführt wurde.

Setzen Sie auth.password.enabled: true, um die gesamte Website zu sperren, oder listen Sie unter auth.password.private[] Pfade auf, um nur diese Seiten zu schützen. Beide Varianten lösen beim nächsten Build dieselbe Passwortabfrage im Dashboard aus.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask your account manager",
      "public": ["/marketing/**", "/changelog"]
    }
  }
}

Siehe Password Protection für die vollständige Anleitung einschließlich des Dashboard-Ablaufs und der Interaktion von public: true / private: true im Frontmatter mit diesen Arrays.

auth.jwt

Typ: object (optional)

Schützen Sie die gesamte Website mit Ihrem eigenen Anmeldesystem. Ihr Backend signiert für jeden angemeldeten Benutzer ein kurzlebiges Token, und Jamdesk tauscht es gegen ein Sitzungscookie aus. Der Signaturschlüssel wird im Dashboard generiert, nicht in dieser Datei. auth.jwt und auth.password können nicht gleichzeitig aktiviert sein; ein Build mit beiden Einstellungen schlägt mit einem config_error fehl.

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/**", "/status"]
    }
  }
}

Der seitenweise Zugriff darüber hinaus wird durch groups im Frontmatter der Seite festgelegt. Siehe JWT Authentication zum Tokenformat, zum Weiterleitungsablauf und zur Funktionsweise von Gruppen.

Vollständiges Beispiel

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Documentation",
  "description": "Learn how to use Acme",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "favicon": "/images/favicon.svg",
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "api": {
    "openapi": ["/openapi/api.yaml"],
    "playground": {
      "display": "interactive"
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "prefill": true
    }
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "spellcheck": {
    "ignore": ["Acme"]
  },
  "anchors": [
    { "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
  ],
  "navbar": {
    "links": [
      { "label": "Support", "href": "/support" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "href": "https://app.acme.com"
    }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Get Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/posts"]
          }
        ]
      }
    ]
  }
}

Wie geht es weiter?