Was ist Mintlify Docs und wie man es benutzt: Ein Leitfaden für Anfänger

Kämpfen Sie damit, elegante, benutzerfreundliche Dokumentationen zu erstellen, die sich nicht wie eine lästige Pflicht anfühlt? Sagen Sie Hallo zu Mintlify, der KI-nativen Plattform, die das Erstellen von beeindruckenden Dokumenten so einfach macht wie das Schreiben eines Blog-Beitrags. Mit über 28.000+ GitHub-Sternen und Kunden wie Stripe bietet Mintlify interaktive Funktionen, KI-Tools und nahtlose Integrationen, um Ihr Dokumentationsspiel auf ein neues Level zu heben. In diesem Leitfaden für Anfänger führe ich Sie durch die Installation von Mintlify, das Einrichten einer benutzerdefinierten Domain, die Nutzung der KI-Aufnahme, die Integration eines MCP-Servers, das Hinzufügen von Übersetzungen und die Verwendung von OpenAPI für API-Dokumente. Egal, ob Sie Entwickler oder Teamleiter sind, Sie werden im Handumdrehen Dokumente auf Profi-Niveau erstellen. Bereit, das Dokumentieren zum Vergnügen zu machen? Los geht's!

💡

Bevor wir beginnen, wenn Sie Ihre API-Entwicklung optimieren möchten, bietet Apidog eine All-in-One-Plattform zum Entwerfen, Testen und Dokumentieren von APIs. Mit seiner intuitiven Benutzeroberfläche und den robusten Funktionen ist es perfekt für Anfänger und erfahrene Entwickler. Das Beste daran ist, dass Sie kostenlos starten können! (apidog)

button

Was ist Mintlify? Ihre Docs-Superpower

Mintlify ist eine moderne Dokumentationsplattform, die Entwicklern hilft, schöne, interaktive und SEO-freundliche Dokumente mit minimalem Aufwand zu erstellen. Sie wurde für Teams und Open-Source-Projekte entwickelt und rendert Markdown- und MDX-Dateien in responsive Seiten, unterstützt die GitHub-Integration und bietet KI-gestützte Funktionen wie Code-Generierung und Übersetzungen. Zu den wichtigsten Vorteilen gehören:

WYSIWYG Editor: Bearbeiten Sie Dokumente in einer browserbasierten Oberfläche.
Interactive Components: Fügen Sie Registerkarten, Code-Snippets und API-Playgrounds hinzu.
AI Optimization: Verbessern Sie die Suche und Barrierefreiheit mit KI-Aufnahme.
Customizable: Passen Sie Themes, Schriftarten und Navigation über eine docs.json-Datei an.

Mit einem Drag-and-Drop-Workflow und 40 % höheren Benutzerkonversionsraten ist Mintlify perfekt für Startups oder öffentliche Projekte. Richten wir es ein

Installieren und Einrichten von Mintlify

Der Einstieg in Mintlify ist ein Kinderspiel, und Sie benötigen Node.js, die Mintlify CLI und ein GitHub-Konto. So geht's los, basierend auf der offiziellen Anleitung.

1. Installieren Sie die Voraussetzungen:

Node.js: Laden Sie Version 16.6 oder höher von https://nodejs.org/ herunter. Überprüfen Sie mit node -v.
GitHub-Konto: Melden Sie sich unter github.com an, falls Sie noch keines haben.
VS Code: Optional, aber für die Bearbeitung empfohlen. Holen Sie es sich von code.visualstudio.com.

2. Klonen Sie das Starter Kit:

Klonen Sie im Terminal das Mintlify Starter Kit:

git clone https://github.com/mintlify/starter-kit
cd starter-kit

Dadurch wird ein Projekt mit einem docs-Ordner erstellt, der MDX-Dateien und eine docs.json-Datei für Einstellungen enthält.

3. Installieren Sie die Mintlify CLI:

Installieren Sie die CLI global:

npm install -g mintlify-cli

Überprüfen Sie mit mintlify-cli --version (z. B. mintlify-cli version 3.1.25).

4. Führen Sie die lokale Vorschau aus:

Starten Sie im starter-Ordner den Entwicklungsserver:

mintlify-cli dev

Dadurch wird eine Vorschau unter http://127.0.0.1:3000 geöffnet. Wenn Port 3000 belegt ist, wird 3001 versucht, oder verwenden Sie --port 3333, um dies anzupassen (z. B. mintlify-cli dev --port=3333).

5. Bearbeiten Sie Ihre Dokumente:

Öffnen Sie das Projekt in VS Code (code .).
Navigieren Sie zu docs/introduction.mdx und ändern Sie das Feld "Titel" in "Willkommen bei meinen Dokumenten!" Speichern Sie, und die Vorschau wird sofort aktualisiert.
Erkunden Sie docs.json, um Schriftarten, Farben anzupassen oder den Dark Mode zu aktivieren. Zum Beispiel:

{
  "name": "My Docs",
  "theme": "prism",
  "colors": { "primary": "#3498db" }
}

Unter https://mintlify.com/docs finden Sie globale Einstellungen wie Symbole oder Logos.

Ich habe dies in weniger als 10 Minuten eingerichtet und hatte eine Live-Site mit meinen Anpassungen – super reibungslos!

Einrichten einer benutzerdefinierten Domain für Mintlify

Möchten Sie, dass Ihre Dokumente unter docs.yourcompany.com statt einer mintlify.app-Subdomain leben? Mintlify macht benutzerdefinierte Domains einfach.

1. Zugriff auf Einstellungen:

Melden Sie sich in Ihrem Mintlify-Dashboard unter mintlify.com an.
Gehen Sie zu Einstellungen > Benutzerdefinierte Domain.

2. Fügen Sie Ihre Domain hinzu:

Geben Sie Ihre Domain ein (z. B. docs.yourcompany.com).
Befolgen Sie die DNS-Anweisungen für Ihren Anbieter (z. B. Namecheap, GoDaddy):
Fügen Sie einen CNAME-Eintrag hinzu: docs → cname.vercel-dns.com.
Aktivieren Sie für Cloudflare die "full strict" HTTPS-Sicherheit.
Wenn Sie Vercel verwenden, fügen Sie einen TXT-Verifizierungseintrag hinzu (im Dashboard angezeigt).

3. Warten Sie auf die Ausbreitung:

DNS-Änderungen dauern bis zu 48 Stunden, werden aber oft schneller aufgelöst. Überprüfen Sie Ihre Domain in einem Browser, um dies zu bestätigen.

Ich habe eine benutzerdefinierte Domain für eine Testseite eingerichtet, und sie war in ein paar Stunden live – professionelle Vibes auf ganzer Linie!

Nutzung der KI-Aufnahme mit Mintlify

Die KI-Aufnahme von Mintlify macht Ihre Dokumente intelligenter und zugänglicher, sodass Benutzer Inhalte über KI-gestützte Abfragen durchsuchen können.

1. Aktivieren Sie die KI-Aufnahme:

Gehen Sie im Mintlify-Dashboard zu Produkte > KI-Chat.
Schalten Sie die KI-Aufnahme ein. Dadurch werden Ihre Dokumente für die KI-Suche indiziert, ohne dass zusätzliche Einstellungen erforderlich sind.
Mintlify generiert automatisch eine /llms.txt-Sitemap, damit LLMs Ihre Inhalte effizient indizieren können.

2. Testen Sie die KI-Suche:

Verwenden Sie in Ihren Live-Dokumenten die Suchleiste oder den KI-Chat (falls über docs.json aktiviert).
Fragen Sie: "Wie authentifiziere ich mich bei der API?" Die KI zieht relevante Abschnitte ab, z. B. Ihre Authentifizierungsseite.

3. Verbessern Sie mit KI-Korrekturen:

Im Web-Editor schlägt die KI Syntaxkorrekturen für MDX-Fehler vor (z. B. fehlerhafte Komponenten). Aktivieren Sie dies unter Einstellungen > Editor.

Ich habe die KI-Suche auf einer Beispielseite ausprobiert, und sie hat meine API-Dokumente sofort gefunden – viel schneller als manuelles Browsen!

Integration eines MCP-Servers mit Mintlify

Das Model Context Protocol (MCP) ermöglicht es KI-Apps, mit Ihren Dokumenten oder APIs zu interagieren. Mintlify generiert einen MCP-Server, um Ihre Inhalte mit LLMs zu verbinden.

1. Installieren Sie die MCP CLI:

Führen Sie aus:

npm i @mintlify/mcp

Gehen Sie im Mintlify-Dashboard zu Produkte > MCP-Server, um Ihren eindeutigen Installationsbefehl zu erhalten.

2. Konfigurieren Sie den MCP-Server:

Suchen Sie Ihren External Admin Key und Chat API Key unter Einstellungen > API-Schlüssel.
Führen Sie den CLI-Befehl aus dem Dashboard aus und geben Sie die Schlüssel ein, wenn Sie dazu aufgefordert werden.
Schalten Sie OpenAPI-Zugriff ein, um API-Endpunkte einzuschließen (erfordert eine OpenAPI-Spezifikation).

3. Verwenden Sie den MCP-Server:

Die CLI gibt einen Befehl aus, um Ihren Server zu starten (z. B. npm --prefix ~/.mcp/mintlify start).
Testen Sie mit einem MCP-Client wie Windsurf, indem Sie abfragen: "Suchen Sie in meinen Dokumenten nach API-Authentifizierung." Der Server gibt strukturierte Ergebnisse zurück.

Lokales Installieren des Mintlify MCP-Servers

So führen Sie den Mintlify MCP-Server auf Ihrem Computer aus:

Führen Sie aus:

npx @mintlify/mcp add mintlify

Überspringen Sie die Eingabeaufforderung für das Bearer-Token, indem Sie die Eingabetaste drücken.
Wählen Sie Ihren MCP-Client (z. B. Claude Desktop, Windsurf), der lokal installiert ist.
Der Server wird für Ihren ausgewählten Client installiert und konfiguriert.

Beispiel: Ich habe Windsurf verwendet, und das Terminal gab mir:

node C:\User\Me.mcp\mintlify\src\index.js

Führen Sie diesen Befehl aus, klicken Sie auf das Werkzeugsymbol in Ihrem Client und überprüfen Sie, ob der Server verfügbar ist.
Gehen Sie alternativ im Mintlify-Dashboard zu MCP-Server, um einen Befehl zu finden, mit dem Sie den Server zu Ihrem MCP-Client (z. B. Apple DB) hinzufügen können.

Beispielaufforderung (in Windsurf):

Schreiben Sie ein Hilfedokument zu dieser Funktion basierend auf diesem PRD, im Stil und Ton der AppleDB-Dokumente.

Oder, für das Mintlify-kompatible Format:

Schreiben Sie dies in Markdown mit Mintlify-Komponenten wie Ankern.

Kopieren Sie die Ausgabe von Ihrem mcp-Client (z. B. Windsurf oder Claude Desktop), fügen Sie sie in den Web-Editor von Mintlify ein, wechseln Sie in den visuellen Modus und zeigen Sie eine Vorschau an!

Ich habe einen MCP-Server eingerichtet, und er ließ meinen KI-Assistenten meine Dokumente wie ein Profi abfragen – futuristisches Zeug!

Hinzufügen von Übersetzungen zu Mintlify-Dokumenten

Möchten Sie Ihre Dokumente in mehreren Sprachen? Die KI-gestützten Übersetzungen von Mintlify machen die Lokalisierung zum Kinderspiel.

1. Aktivieren Sie Übersetzungen:

Gehen Sie im Mintlify-Dashboard zu Einstellungen > Übersetzungen.
Fügen Sie ein Gebietsschema hinzu (z. B. es für Spanisch) und wählen Sie eine zu übersetzende Version aus.
Mintlify übersetzt Ihre Dokumente automatisch und synchronisiert Aktualisierungen mit der Hauptversion.

2. Passen Sie Übersetzungen an:

Bearbeiten Sie übersetzte MDX-Dateien im Gebietsschema-Ordner Ihres Repositorys (z. B. docs/es/).
Fester Inhalt wie "War diese Seite hilfreich?" passt sich automatisch an das Gebietsschema an.

3. Testen Sie die Übersetzung:

Wechseln Sie in Ihren Live-Dokumenten die Gebietsschemas über das Versions-Dropdown (konfiguriert in docs.json).

Überprüfen Sie, ob Titel und Inhalt die Zielsprache widerspiegeln (z. B. "¡Bienvenidos!" für Spanisch).

Ich habe spanische Übersetzungen hinzugefügt, und meine Dokumente waren in wenigen Minuten global einsatzbereit – ein riesiger Gewinn für die Barrierefreiheit!

Verwenden von Mintlify mit VS Code

Code in VS Code dokumentieren? Die Erweiterung von Mintlify macht es zum Kinderspiel!

1. Installieren Sie die Mintlify-Erweiterung:

Öffnen Sie den Extension Marketplace von VS Code.
Suchen Sie nach "Mintlify" und klicken Sie auf Installieren.

2. Generieren Sie Dokumentation:

Markieren Sie den Code, den Sie dokumentieren möchten.
Klicken Sie auf das Mintlify-Symbol in der Seitenleiste und wählen Sie Dokumente generieren oder verwenden Sie die Verknüpfung Strg + ..
Mintlify schreibt automatisch Dokumentation.

Beispielcode:

test("@e2e wait for api response", async ({ page }) => {
  const sidemenuPage = new SideMenuPage(page);
  await sidemenuPage.interceptApiLink.click();
  const response = await page.waitForResponse((response) =>
    response.url().includes("/comments")
  );
  expect(response.status()).toBe(200);
  await page.getByText("CREATE post").isVisible();
});

Generierte Dokumentation:

Der Codeblock ist ein Testfall, der prüft, ob die API-Antwort erfolgreich empfangen wurde.

Ich habe ein Testskript dokumentiert, und Mintlify hat die Beschreibung perfekt getroffen – mühelos!

Erkunden der Funktionen von Mintlify

Mintlify ist vollgepackt mit Tools, um Ihre Dokumente zum Glänzen zu bringen. So geht's:

Web Editor: Bearbeiten Sie Dokumente im Browser über Dashboard > Editor. Geben Sie / für Komponenten wie Registerkarten oder Callouts ein.
Themes und Styling: Passen Sie Farben, Schriftarten oder Logos in docs.json an. Probieren Sie Themes wie prism oder default aus.
GitHub-Integration: Installieren Sie die Mintlify GitHub App, um Änderungen automatisch bereitzustellen. Überprüfen Sie das Dashboard für die Einrichtung.
Analytics: Verfolgen Sie das Benutzerengagement in Dashboard > Analytics, um beliebte Seiten oder Abbrüche zu sehen.
Components: Fügen Sie Akkordeons, Codegruppen oder Mermaid-Diagramme über MDX hinzu. Siehe https://mintlify.com/docs für Beispiele.

Ich habe mein Theme angepasst und Registerkarten hinzugefügt, wodurch meine Dokumente in weniger als einer Stunde wie ein Profi-Design aussahen!

Zusammenfassung: Ihre Mintlify-Reise beginnt

Super gemacht – Sie haben die Leistungsfähigkeit von Mintlify freigeschaltet, um beeindruckende, KI-fähige Dokumentationen zu erstellen! Von der Installation der CLI über das Einrichten benutzerdefinierter Domains, KI-Aufnahme, MCP-Server, Übersetzungen und OpenAPI-Playgrounds sind Sie bereit, Dokumente zu erstellen, die Benutzer begeistern. Experimentieren Sie mit neuen Komponenten, fügen Sie weitere Sprachen hinzu oder dokumentieren Sie Ihre APIs mit APIdog! Viel Spaß beim Dokumentieren!

button