Schnellstart

Stellen Sie Ihre Dokumentation in wenigen Minuten bereit

Dieser Schnellstartleitfaden zeigt Ihnen, wie Sie Ihre Dokumentationswebsite in wenigen Minuten einrichten und bereitstellen.

Nach Abschluss dieses Leitfadens haben Sie eine Live-Dokumentationswebsite, die Sie anpassen und erweitern können.

Voraussetzungen: Bevor Sie beginnen, erstellen Sie ein Konto und schließen Sie das Onboarding ab.

Erste Schritte

Nachdem Sie den Onboarding-Prozess abgeschlossen haben, wird Ihre Dokumentationsseite automatisch unter einer eindeutigen URL mit folgendem Format bereitgestellt:

https://<your-project-name>.mintlify.app

Sie finden Ihre URL auf der Übersichtsseite Ihres Dashboards.

Die URL Ihrer Seite ist sofort verfügbar. Verwenden Sie sie zum Testen und zum Teilen mit Ihrem Team, während Sie Ihre Docs-Website einrichten.

GitHub-App installieren

Mintlify bietet eine GitHub-App, die die Bereitstellung automatisiert, sobald du Änderungen in dein Repository pushst.

Installiere die GitHub-App, indem du den Anweisungen in der Onboarding-Checkliste oder in deinem Dashboard folgst.

1. Navigiere zu Settings in deinem Mintlify-Dashboard.
2. Wähle GitHub App in der Seitenleiste.
3. Wähle Install GitHub App. Dadurch wird ein neuer Tab mit der Installationsseite der GitHub-App geöffnet.
4. Wähle die Organisation oder das Benutzerkonto aus, in dem du die App installieren möchtest.
5. Wähle die Repositories aus, die du verbinden möchtest.

Aktualisiere die Berechtigungen der GitHub-App, wenn du deine Dokumentation in ein anderes Repository verschiebst.

Autorisieren Sie Ihr GitHub-Konto

1. Navigieren Sie zu Settings in Ihrem Mintlify-Dashboard.
2. Wählen Sie My Profile in der Seitenleiste.
3. Wählen Sie Authorize GitHub account. Dadurch wird ein neuer Tab mit der GitHub-Autorisierungsseite geöffnet.

Abhängig von den Einstellungen Ihrer Organisation muss möglicherweise ein Administrator Ihrer GitHub-Organisation Ihr Konto autorisieren.

Bearbeitungs-Workflows

Mintlify bietet zwei Workflows zum Erstellen und Pflegen Ihrer Dokumentation:

Codebasierter Workflow

Für Nutzer, die bevorzugt mit bestehenden Tools in ihrer lokalen Umgebung arbeiten. Klicken, um zu diesem Abschnitt zu springen.

Web-Editor-Workflow

Für Nutzer, die eine visuelle Oberfläche in ihrem Webbrowser bevorzugen. Klicken, um zu diesem Abschnitt zu springen.

Codebasierter Workflow

Der codebasierte Workflow fügt sich in Ihre bestehende Entwicklungsumgebung und Ihre Git-Repositories ein. Dieser Workflow ist ideal für technische Teams, die Dokumentation gemeinsam mit dem Code verwalten möchten.

CLI installieren

Um lokal mit deiner Dokumentation zu arbeiten, installiere die Command Line Interface (CLI) namens mint, indem du diesen Befehl in deinem Terminal ausführst:

npm

npm i -g mint

Du benötigst Node.js auf deinem Rechner. Wenn bei der Installation Probleme auftreten, lies den Troubleshooting-Guide.

Dokumentation bearbeiten

Nachdem Sie Ihre Umgebung eingerichtet haben, können Sie mit der Bearbeitung Ihrer Dokumentationsdateien beginnen. Aktualisieren Sie zum Beispiel den Titel der Einführungsseite:

1. Öffnen Sie das Repository, das während des Onboardings erstellt wurde.
2. Öffnen Sie index.mdx und gehen Sie zum Anfang der Datei:

index.mdx

---
title: "Introduction"
description: "This is the introduction to the documentation"
---

3. Aktualisieren Sie das Feld title auf „Hello World“.

index.mdx

---
title: "Hello World"
description: "This is the introduction to the documentation"
---

Änderungen in der Vorschau anzeigen

Um die Änderungen lokal anzuzeigen, führen Sie den folgenden Befehl aus:

mint dev

Die Vorschau ist unter localhost:3000 verfügbar.

Änderungen pushen

Wenn Sie bereit sind, Ihre Änderungen zu veröffentlichen, pushen Sie sie in Ihr Repository.

Mintlify erkennt die Änderungen automatisch, baut Ihre Dokumentation und stellt die Updates auf Ihrer Site bereit. Überwachen Sie den Bereitstellungsstatus in der Commit-Historie Ihres GitHub-Repos oder im Dashboard.

Nach Abschluss der Bereitstellung ist Ihr neuestes Update unter <your-project-name>.mintlify.app verfügbar.

Zum Hinzufügen einer benutzerdefinierten Domain springen

Überspringen Sie bei Bedarf den Web-Editor-Workflow und springen Sie direkt zum Hinzufügen einer benutzerdefinierten Domain.

Web-Editor-Workflow

Der Web-Editor-Workflow bietet eine WYSIWYG-Oberfläche (What You See Is What You Get) zum Erstellen und Bearbeiten von Dokumentationen. Dieser Workflow eignet sich besonders für Personen, die direkt im Webbrowser arbeiten möchten – ohne zusätzliche lokale Entwicklungstools.

Zugriff auf den Web-Editor

1. Melden Sie sich in Ihrem Dashboard an.
2. Wählen Sie Editor in der linken Seitenleiste.

Wenn Sie die GitHub-App noch nicht installiert haben, werden Sie beim Öffnen des Web-Editors dazu aufgefordert.

Dokumentation bearbeiten

Im Web-Editor kannst du in der Seitenleiste durch deine Dokumentationsdateien navigieren. Aktualisieren wir die Einführungsseite:

Suche und wähle index.mdx im Dateiexplorer aus.

Aktualisiere dann im Editor das Titelfeld auf „Hello World“.

Der Editor bietet eine umfangreiche Sammlung an Formatierungswerkzeugen und Komponenten. Tippe / im Editor, um das Befehlsmenü zu öffnen und diese Werkzeuge aufzurufen.

Änderungen veröffentlichen

Wenn Sie mit Ihren Anpassungen zufrieden sind, klicken Sie oben rechts auf Publish. Ihre Änderungen werden sofort auf Ihrer Dokumentationsseite bereitgestellt.

Verwenden Sie Branches, um Änderungen per Pull Requests vor dem Livegang vorab zu prüfen und zu reviewen.

Weitere Details zur Verwendung des Web-Editors – einschließlich der Zusammenarbeit mit Branches und Pull Requests sowie dem Vorab-Ansehen von Änderungen – finden Sie in unserer Web-Editor-Dokumentation.

Eine benutzerdefinierte Domain hinzufügen

Während Ihre Subdomain <your-project-name>.mintlify.app sich gut für Tests und Entwicklung eignet, bevorzugen die meisten Teams für die produktive Dokumentation eine benutzerdefinierte Domain.

Um eine benutzerdefinierte Domain hinzuzufügen, navigieren Sie in Ihrem Dashboard zur Seite Domain Setup.

Geben Sie Ihre Domain ein (zum Beispiel docs.yourcompany.com) und folgen Sie den Anweisungen, um die DNS-Einstellungen bei Ihrem Domain-Provider zu konfigurieren.

DNS-Änderungen können bis zu 48 Stunden dauern, bis sie weltweit wirksam werden, häufig geht es jedoch deutlich schneller.

Nächste Schritte

Herzlichen Glückwunsch! Sie haben Ihre Dokumentationsseite mit Mintlify erfolgreich bereitgestellt. Hier sind empfohlene nächste Schritte, um Ihre Dokumentation weiter zu verbessern:

Globale Einstellungen konfigurieren

Konfigurieren Sie standortweite Gestaltung, Navigation, Integrationen und mehr in der Datei docs.json.

Theme anpassen

Erfahren Sie, wie Sie Farben, Schriftarten und das Gesamterscheinungsbild Ihrer Dokumentationsseite anpassen.

Navigation organisieren

Strukturieren Sie Ihre Dokumentation mit einer intuitiven Navigation, damit Nutzende schnell finden, was sie benötigen.

Interaktive Komponenten hinzufügen

Verbessern Sie Ihre Dokumentation mit interaktiven Komponenten wie Accordions, Tabs und Codebeispielen.

API-Referenzen einrichten

Erstellen Sie interaktive API-Referenzen mit OpenAPI- und AsyncAPI-Spezifikationen.

Fehlerbehebung

Wenn während der Einrichtung Probleme auftreten, prüfen Sie diese gängigen Lösungen:

Lokale Vorschau funktioniert nicht

Stellen Sie sicher, dass Node.js v19+ installiert ist und dass Sie den Befehl mint dev in dem Verzeichnis ausführen, das Ihre docs.json enthält.

Änderungen werden auf der Live‑Site nicht angezeigt

Die Bereitstellung kann einige Minuten dauern. Überprüfen Sie Ihre GitHub Actions (bei codebasierten Workflows) oder die Bereitstellungsprotokolle im Mintlify‑Dashboard, um sicherzustellen, dass keine Build‑Fehler auftreten.

Eigene Domain wird nicht verbunden

Prüfen Sie, ob Ihre DNS‑Einträge korrekt konfiguriert sind, und geben Sie der DNS‑Propagation ausreichend Zeit (bis zu 48 Stunden). Mit Tools wie DNSChecker können Sie Ihren CNAME‑Eintrag überprüfen.