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 wird mit einer abgestimmten Standardschrift ausgeliefert. Setzen Sie fonts nur, wenn Sie ein anderes Erscheinungsbild benötigen.

Verwenden Sie überall dieselbe Schriftart:

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

Überschrift und Fließtext aufteilen:

{
  "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 Schriftarten.

Darstellung

appearance

Typ: object (optional)

Steuern Sie das standardmäßige Verhalten des Dunkelmodus 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 daher ihr ursprüngliches Datum.

Banner

banner

Zeigen Sie oben auf jeder Seite über dem Header eine Website-weite Ankündigungsleiste in voller Breite und in der Akzentfarbe Ihres Themes an. Verwenden Sie sie für Launches, 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 aufgeführt haben, können Sie auch das Kurzformat verwenden:

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

Siehe OpenAPI Example für eine live angezeigte Endpoint-Seite und Directory Structure für die Ablage der 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.

api.examples.languages

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

Wählen Sie aus, welche Programmiersprachen in automatisch generierten API-Codebeispielen auf openapi:-Seiten angezeigt werden. Die Reihenfolge des Arrays bestimmt die Reihenfolge der Tabs; standardmäßig wird die erste Programmiersprache 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 angezeigt werden.

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

api.examples.prefill

Typ: boolean Standard: false

Wenn true, füllt das API Playground Parameterfelder auf Endpoint-Seiten vorab mit example-Werten aus Ihrer OpenAPI-Spezifikation aus.

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

api.playground.display

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

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

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

Siehe API Playground für Nutzungsdetails und seitenspezifische Überschreibungen.

api.mdx.auth.method

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

Authentifizierungsmethode für automatisch generierte Codebeispiele. Wenn gesetzt, enthalten die Beispiele den passenden Authentifizierungsheader.

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

api.mdx.auth.name

Typ: string

Benutzerdefinierter Headername für die 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 die Navigationstabs angezeigt werden.

Der Standardwert hängt vom Theme ab:

{ "tabsPosition": "left" }

anchors

Typ: array

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

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

navigation (structure)

Typ: object

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

Seiten können Zeichenfolgen sein (der Titel wird 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 Seitenfußzeile mit Social-Media-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 Social-Media-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 die Darstellung mathematischer LaTeX-Ausdrücke mit KaTeX. Wenn aktiviert, können Sie $...$ für Inline-Mathematik und $$...$$ für Blockgleichungen verwenden.

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

Siehe Math & LaTeX für 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"
  }
}

Für mehrere Dateien übergeben Sie ein Array:

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

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

Suche

search

Typ: object (optional)

Passen Sie die Suchleiste der Dokumentation an. Die Suche funktioniert sofort; Sie benötigen dieses Feld nur, um den Platzhaltertext zu ändern oder beliebte Seiten im leeren Zustand anzuzeigen.

{
  "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-Chatassistenten. Der Chat ist standardmäßig auf allen Websites aktiviert; Sie benötigen dieses Feld 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.

KI-Aktionsmenü

contextual

Typ: object (optional)

Konfigurieren Sie das Dropdown-Menü für KI-Aktionen, das auf jeder Seite angezeigt wird. Es ist standardmäßig mit allen Optionen aktiviert; Sie benötigen dieses Feld 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 den 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. Sie benötigen dieses Feld 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 für Nutzungsdetails und den 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 in der Regel 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 stellt WebP zuverlässig dar, und eine fehlerhafte Vorschaukarte ist schlechter als ein etwas größeres JPG.

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

Siehe Automatic Image Conversion, um zu erfahren, was konvertiert wird, wie das Caching funktioniert und wie der Build-Fortschrittsindikator eingesetzt wird.

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 nach dem nächsten Build weiterhin im Dashboard fest.

Setzen Sie auth.password.enabled: true, um die gesamte Website zu sperren, oder listen Sie Pfade unter auth.password.private[] auf, um nur bestimmte 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 Wechselwirkung von public: true / private: true im Frontmatter mit diesen Arrays.

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?