Bei der Bereitstellung moderner Entwicklerdokumentationen setzen immer mehr Engineering- und Technical-Writing-Teams auf Mintlify. Anstatt komplexe Frontend-Routing-Logiken oder benutzerdefinierte CSS-Dateien mühsam von Hand zu pflegen, verfolgt Mintlify den Ansatz „Docs-as-Code“. Die gesamte visuelle Identität und Informationsarchitektur wird in einer einzigen deklarativen Konfigurationsdatei im Wurzelverzeichnis des Repositories gebündelt: docs.json (in früheren Versionen mint.json). Teams definieren globale Markenressourcen, mehrstufige Seitenleisten, einklappbare Abschnitte und bereichsübergreifende Tab-Gruppen direkt in versioniertem JSON neben ihren MDX-Inhalten.
Dieser Leitfaden erläutert praxisnah, wie technische Dokumentationsteams docs.json einsetzen, um ein konsistentes Markenbild aufzubauen, Seitenleisten strukturiert zu gliedern und horizontale Tab-Gruppen für komplexe Entwicklerportale einzurichten.
1. Zentrale Konfigurationsarchitektur: Die docs.json-Spezifikation
Jede Mintlify-Instanz wird über die Datei docs.json im Stammverzeichnis des Repositories gesteuert. Die aktuelle Spezifikation vereint Layout-Themes, Navigationsbäume, API-Playground-Optionen und Drittanbieter-Integrationen in einem einheitlichen Datenschema.
Schemavalidierung und Datei-Auflösungsregeln
Um automatische Code-Vervollständigung, Syntaxvalidierung und Inline-Dokumentation in Editoren wie VS Code zu nutzen, empfiehlt sich die Angabe des offiziellen JSON-Schemas am Anfang von docs.json:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme Entwicklerportal",
"theme": "maple"
}
Wichtige Dateisystem- und Pfadkonventionen in Mintlify:
- Pfade ohne Dateiendung: Alle in Navigationslisten deklarierten Pfade beziehen sich relativ auf das Projekt-Wurzelverzeichnis und lassen die Endung
.mdxbzw..mdweg. Der Eintrag"pages": ["getting-started/quickstart"]verweist somit auf die physische Dateigetting-started/quickstart.mdx. - Git-gestützte Zusammenarbeit: Strukturänderungen, neue Seiten und Farbkorrekturen werden als reine Textunterschiede versioniert und über Pull Requests mit Code-Reviews und automatischen Vorschau-Deployments geprüft.
- Synchronisation mit dem Web-Editor: Wenn Redakteure Seiten im visuellen Cloud-Editor von Mintlify per Drag-and-Drop verschieben, erzeugt das System automatisch Git-Commits, die
docs.jsonaktualisieren.
2. Benutzerdefiniertes Branding und visuelle Identität
Mintlify ermöglicht es, Dokumentationsportale exakt an bestehende Corporate-Design-Systeme anzupassen, ohne instabile CSS-Hacks einsetzen zu müssen. Sämtliche Markeneigenschaften werden auf oberster Ebene in docs.json konfiguriert.
Layout-Themes
Über die Eigenschaft theme stellt Mintlify vordefinierte Layout-Engines bereit:
mint: Das bewährte, klassische Dokumentationslayout, ideal für Open-Source-Software und Bibliotheken.maple: Eine moderne, aufgeräumte Ästhetik, die häufig bei SaaS-Plattformen und KI-Tools genutzt wird.palm: Ein dicht strukturiertes Layout mit hoher Informationstiefe, optimal für Fintech und Enterprise-Plattformen.willow: Ein minimalistisches Layout mit Fokus auf ablenkungsfreies Lesen.- Weitere verfügbare Themes sind
linden,almond,aspen,sequoiaundluma.
Markenfarben und Dark-Mode-Anpassung
Das Objekt colors steuert die Kernfarben der Benutzeroberfläche und sorgt für lesbare Kontrastverhältnisse im Hell- und Dunkelmodus:
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary: Die primäre Markenfarbe für Links, aktive Statusanzeigen und wichtige Schaltflächen im Hellmodus.light: Die Akzentfarbe für den Dunkelmodus, optimiert für kontrastreiche Lesbarkeit auf dunklen Hintergründen.dark: Wird für Hover-Effekte und sekundäre Interaktionselemente in beiden Modi verwendet.
Dual-Mode-Logos und Favicon
Um auf hellem wie auf dunklem Hintergrund maximale Schärfe zu garantieren, sollten separate SVG-Vektorgrafiken zusammen mit einer Ziel-URL hinterlegt werden:
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
Wird logo.href nicht angegeben, führt ein Klick auf das Logo standardmäßig zur Startseite der Dokumentation.
Typografie, Icon-Bibliotheken und Hintergrund
- Schriftarten: In
fontskönnen Schriftfamilien aus Google Fonts (wie"Inter"oder"Fira Code") direkt angegeben werden. Ebenso lassen sich selbst gehostete.woff2-Dateien einbinden und unterschiedliche Schriften für Überschriften (fonts.heading) und Fließtext (fonts.body) definieren. - Icons: Mintlify unterstützt Font Awesome, Lucide und Tabler. Mit
"icons": { "library": "lucide" }können in der Navigation Standard-Icon-Namen wie"book-open"oder"terminal"verwendet werden. Auch Inline-SVGs und Emojis werden unterstützt. - Hintergrunddekoration: Mit
"background": { "decoration": "gradient" }oder"grid"lässt sich der Hintergrund dezent akzentuieren. - Erzwungener Farbmodus: Verlangt die Markenidentität ausschließlich einen dunklen Hintergrund, kann über
"appearance": { "default": "dark", "strict": true }der Farbmodus fixiert und der Umschalter für Nutzer ausgeblendet werden.
3. Aufbau der Navigationsseitenleiste: Gruppen, Verschachtelung und Root-Seiten
Die Seitenleiste orientiert den Leser und führt ihn strukturiert durch Anleitungen und Referenztexte. In Mintlify wird sie vollständig im Objekt navigation definiert.
Standardgruppen und Gruppen mit Icons
Eine Gruppe fasst inhaltlich zusammenhängende Seiten unter einer gemeinsamen Überschrift zusammen. Erforderlich sind der Gruppenname group und das Array pages:
"navigation": {
"groups": [
{
"group": "Erste Schritte",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
Mehrstufige Verschachtelung und Standard-Klappzustand
Mit wachsendem Dokumentationsumfang führt eine flache Liste schnell zu Unübersichtlichkeit. Mintlify erlaubt es, Untergruppen direkt im pages-Array einer übergeordneten Gruppe zu verschachteln.
Um die Seitenleiste kompakt zu halten, steuert die boolesche Eigenschaft expanded den initialen Aufklappzustand:
{
"group": "Kernarchitektur",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "Datenspeicherschicht",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "Sicherheit & Compliance",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
Hinweis: Hauptgruppen der obersten Ebene sind in der Seitenleiste stets geöffnet. Die Eigenschaft expanded gilt für verschachtelte Untergruppen.
Klickbare Gruppenüberschriften mit Root-Seiten (root)
Standardmäßig klappt ein Klick auf eine Gruppenüberschrift lediglich die Unterseiten auf oder zu. Oft soll die Überschrift jedoch selbst als einleitende Übersichtsseite dienen.
Über die Eigenschaft root wird die Gruppenüberschrift mit einer MDX-Seite verknüpft:
{
"group": "API-Referenz",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
Klickt der Benutzer auf „API-Referenz“, lädt im Hauptbereich sofort api/overview.mdx, während in der Seitenleiste die zugehörigen Endpunkte sichtbar werden.
Automatische Verzeichnisindizes (directory)
Um die manuelle Pflege von Inhaltsverzeichnissen zu vermeiden, bietet Mintlify für Gruppen mit einer root-Seite das Attribut directory. Das System fügt unterhalb des Inhalts der Einstiegsseite automatisch einen interaktiven Index der untergeordneten Seiten ein.
Unterstützte Optionen für directory:
"card": Zeigt Unterseiten als horizontale, anklickbare Karten mit Titeln und kurzen Beschreibungen an."accordion": Organisiert Unterseiten in einklappbaren Akkordeon-Panels – ideal bei umfangreichen Referenzkatalogen."none": Deaktiviert die automatische Indexgenerierung (Standardwert).
Die directory-Eigenschaft wird hierarchisch an untergeordnete Gruppen vererbt, sodass globale Einstellungen bei Bedarf in tieferen Ebenen überschrieben werden können.
4. Strukturierung von Multi-Produkt-Portalen mit Tab-Gruppen
Wenn ein Entwicklerportal Konzeptionsleitfäden, interaktive API-Referenzen, SDKs in mehreren Programmiersprachen und Release-Notes vereint, überfordert eine einzige lineare Seitenleiste den Leser. Horizontale Tab-Gruppen am oberen Seitenrand gliedern die Dokumentation in logische Hauptdomänen.
Navigations-Tabs auf Website-Ebene
Tabs teilen die Dokumentation in eigenständige Arbeitsbereiche. Jeder Tab besitzt einen eigenen Seitenleistenbaum und einen isolierten URL-Pfadbereich.
Konfiguriert werden Tabs im Array navigation.tabs:
"navigation": {
"tabs": [
{
"tab": "Leitfäden",
"icon": "book-open",
"groups": [
{
"group": "Grundlagen",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "Bereitstellung",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "API-Referenz",
"icon": "square-terminal",
"groups": [
{
"group": "Endpunkte",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "SDKs",
"icon": "code-2",
"groups": [
{
"group": "Client-Bibliotheken",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "Changelog",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
Wechselt der Leser zwischen den Tabs:
- Passt sich die Seitenleiste augenblicklich an und zeigt nur die dem aktiven Tab zugewiesenen Gruppen und Seiten.
- Aktualisiert der Browser die URL mit dem entsprechenden Pfadpräfix.
- Externe Verweise (über
href) fügen sich nahtlos in die Kopfzeile ein und öffnen das gewünschte Ziel.
Dropdown-Menüs innerhalb von Tabs (menu)
Umfasst ein Hauptreiter mehrere eigenständige Produktlinien, kann innerhalb des Tabs ein menu-Array definiert werden, das ein Auswahl-Dropdown in der oberen Navigation erzeugt:
{
"tab": "Produkte",
"icon": "layers",
"menu": [
{
"item": "Payment-Engine",
"icon": "credit-card",
"description": "Integration von Zahlungsgateways und Abrechnungssystemen.",
"groups": [
{
"group": "Erste Schritte",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "Identity Cloud",
"icon": "key-round",
"description": "SSO-, OAuth 2.0- und Verzeichnissynchronisationsstandards.",
"groups": [
{
"group": "Authentifizierung",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
Globale Anker (Anchors) im Vergleich zu Tabs
- Tabs (Reiter): Dienen der horizontalen Aufteilung wesentlicher Dokumentationsbereiche und schalten den gesamten Seitenleisteninhalt um.
- Global Anchors (Globale Anker): Werden unter
navigation.global.anchorsdefiniert und fungieren als permanente Schnellzugriffe am oberen oder unteren Rand der Seitenleiste (z. B. „Systemstatus“, „GitHub-Repository“, „Support-Forum“), die unabhängig vom gewählten Tab stets sichtbar bleiben.
Wichtige Abgrenzung: Website-Tabs vs. <Tabs> in MDX-Dateien
Ein häufiges Missverständnis betrifft den Unterschied zwischen Website-Tabs und MDX-Tabs:
- Website-Navigations-Tabs (
docs.json): Steuern das seitenübergreifende Routing und die Umschaltung der Seitenleisten. - Inhalts-
<Tabs>in MDX: Dienen dem Umschalten von Codebeispielen innerhalb einer einzelnen Dokumentseite (z. B. Wechsel zwischen cURL, TypeScript und Python). Mintlify synchronisiert standardmäßig die aktive Auswahl gleichnamiger Tabs innerhalb einer Seite, sofern dies nicht explizit mitsync={false}deaktiviert wird.
5. Vollständiges Produktionsbeispiel
Nachfolgend finden Sie eine vollständige, praxiserprobte docs.json-Konfiguration mit Markendesign, globalen Ankern, mehreren Tabs, verschachtelten Gruppen und automatischen Kartenverzeichnissen:
{
"$schema": "https://mintlify.com/docs.json",
"name": "CloudScale Dokumentation",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "Systemstatus",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "Slack-Community",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "Produktleitfäden",
"icon": "book-open",
"groups": [
{
"group": "Überblick & Einrichtung",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "Infrastruktur",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "Netzwerk & DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "API-Referenz",
"icon": "square-terminal",
"groups": [
{
"group": "Authentifizierung",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "Compute-API",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. Best Practices für Teams und Fehlervermeidung
Um Dokumentationsportale reibungslos im Team zu skalieren, sollten folgende Leitlinien beachtet werden:
- Lokale Vorabprüfung via Mintlify CLI: Vor jedem Commit oder Push sollten Änderungen mit
npx mintlify devlokal getestet werden. Der lokale Server meldet Tippfehler in Dateipfaden, Syntaxprobleme indocs.jsonund fehlende Dateien unmittelbar. - Exakte Pfadangaben sicherstellen: Jeder String in
"pages"muss exakt einer physischen MDX-Datei entsprechen. Wird eine Datei umbenannt (z. B. vonguides/cli.mdxinguides/cli-tooling.mdx), mussdocs.jsonim selben Commit angepasst werden, um 404-Fehler zu vermeiden. - Farbkontraste im Dark Mode prüfen: Achten Sie bei der Definition von
colors.primarydarauf, dass auchcolors.lightsorgfältig gewählt wird. Ein unzureichender Kontrast auf dunklem Hintergrund erschwert das Lesen von Links und verletzt Barrierefreiheitsstandards nach WCAG AA. - Verschachtelungstiefe der Seitenleiste begrenzen: Die Seitenleiste sollte maximal zwei Ebenen tief verschachtelt sein (Hauptgruppe > Untergruppe > Seite). Tiefere Hierarchien führen auf mobilen Endgeräten zu horizontalem Scrollen und Unübersichtlichkeit; lagern Sie komplexe Unterbereiche stattdessen in Tabs oder Dropdown-Menüs aus.