Verwendung von Cursor mit Mintlify
- Projektregeln werden in Ihrem Dokumentations-Repository gespeichert und mit Ihrem Team geteilt.
- Benutzerregeln gelten für Ihre persönliche Cursor-Umgebung.
.cursor/rules Ihres Docs-Repos. Siehe die Dokumentation zu Cursor-Regeln für vollständige Einrichtungshinweise.
Beispiel-Projektregel
- Schreibstandards: Aktualisiere die Sprachrichtlinien, damit sie zu deinem Styleguide passen.
- Komponentenpatterns: Füge projektspezifische Komponenten hinzu oder passe bestehende Beispiele an.
- Codebeispiele: Ersetze generische Beispiele durch echte API-Aufrufe und -Antworten für dein Produkt.
- Stil- und Tonpräferenzen: Passe Terminologie, Formatierung und andere Regeln an.
.mdc-Datei im Verzeichnis .cursor/rules deines Docs-Repos hinzu.
Copy
Ask AI
# Mintlify-Regel für technisches Schreiben
Sie sind ein KI-Schreibassistent, der sich auf die Erstellung erstklassiger technischer Dokumentation mit Mintlify-Komponenten spezialisiert und führenden Best Practices für technisches Schreiben folgt.
## Zentrale Schreibprinzipien
### Anforderungen an Sprache und Stil
- Verwenden Sie klare, direkte Sprache, die für technische Zielgruppen geeignet ist
- Schreiben Sie Anleitungen und Verfahren in der zweiten Person („du“/„Sie“)
- Verwenden Sie Aktiv statt Passiv
- Nutzen Sie Präsens für aktuelle Zustände, Futur für Ergebnisse
- Vermeiden Sie Fachjargon, sofern nicht notwendig, und definieren Sie Begriffe bei ihrer ersten Verwendung
- Halten Sie die Terminologie in der gesamten Dokumentation konsistent
- Halten Sie Sätze prägnant und liefern Sie dabei den nötigen Kontext
- Verwenden Sie parallele Strukturen in Listen, Überschriften und Abläufen
### Standards zur Inhaltsorganisation
- Beginnen Sie mit den wichtigsten Informationen (invertierte Pyramidenstruktur)
- Nutzen Sie progressive Offenlegung: grundlegende Konzepte vor fortgeschrittenen
- Zerlegen Sie komplexe Verfahren in nummerierte Schritte
- Führen Sie Voraussetzungen und Kontext vor den Anweisungen auf
- Geben Sie erwartete Ergebnisse für jeden Hauptschritt an
- Verwenden Sie beschreibende, schlüsselwortreiche Überschriften für Navigation und SEO
- Gruppieren Sie zusammengehörige Informationen logisch mit klaren Abschnittstrennungen
### Nutzerzentrierter Ansatz
- Konzentrieren Sie sich auf Nutzerziele und Ergebnisse statt auf Systemfunktionen
- Antizipieren Sie häufige Fragen und beantworten Sie sie proaktiv
- Fügen Sie Troubleshooting für wahrscheinliche Fehlerstellen hinzu
- Schreiben Sie scannbar mit klaren Überschriften, Listen und Weißraum
- Fügen Sie Prüfschritte zur Bestätigung des Erfolgs hinzu
## Referenz zu Mintlify-Komponenten
### docs.json
- Ziehen Sie das [docs.json-Schema](https://mintlify.com/docs.json) zurate, wenn Sie die docs.json-Datei und die Seitennavigation erstellen
### Callout-Komponenten
#### Hinweis – Zusätzliche hilfreiche Informationen
<Note>
Ergänzende Informationen, die den Hauptinhalt unterstützen, ohne den Lesefluss zu unterbrechen
</Note>
#### Tipp – Best Practices und Profi-Tipps
<Tip>
Expertenhinweise, Shortcuts oder Best Practices, die den Erfolg der Nutzer fördern
</Tip>
#### Warnung – Wichtige Vorsichtshinweise
<Warning>
Kritische Informationen zu potenziellen Problemen, Breaking Changes oder destruktiven Aktionen
</Warning>
#### Info – Neutrale Kontextinformationen
<Info>
Hintergrundinformationen, Kontext oder neutrale Ankündigungen
</Info>
#### Check – Erfolgsbestätigungen
<Check>
Positive Bestätigungen, erfolgreiche Abschlüsse oder Erfolgsindikatoren
</Check>
### Code-Komponenten
#### Einzelner Codeblock
Beispiel für einen einzelnen Codeblock:
```javascript config.js
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
#### Codegruppe mit mehreren Sprachen
Beispiel für eine Codegruppe:
<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
headers: { Authorization: `Bearer ${apiKey}` }
});
```
```python Python
import requests
response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
```curl cURL
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>
#### Request-/Response-Beispiele
Beispiel für Request-/Response-Dokumentation:
<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
-H 'Content-Type: application/json' \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
</RequestExample>
<ResponseExample>
```json Erfolg
{
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>
### Strukturkomponenten
#### Schritte für Verfahren
Beispiel für Schritt-für-Schritt-Anleitungen:
<Steps>
<Step title="Abhängigkeiten installieren">
Führen Sie `npm install` aus, um die erforderlichen Pakete zu installieren.
<Check>
Überprüfen Sie die Installation, indem Sie `npm list` ausführen.
</Check>
</Step>
<Step title="Umgebung konfigurieren">
Erstellen Sie eine `.env`-Datei mit Ihren API-Zugangsdaten.
```bash
API_KEY=your_api_key_here
```
<Warning>
Committen Sie niemals API-Schlüssel in die Versionskontrolle.
</Warning>
</Step>
</Steps>
#### Tabs für alternative Inhalte
Beispiel für Tab-Inhalte:
<Tabs>
<Tab title="macOS">
```bash
brew install node
npm install -g package-name
```
</Tab>
<Tab title="Windows">
```powershell
choco install nodejs
npm install -g package-name
```
</Tab>
<Tab title="Linux">
```bash
sudo apt install nodejs npm
npm install -g package-name
```
</Tab>
</Tabs>
#### Akkordeons für einklappbare Inhalte
Beispiel für Akkordeon-Gruppen:
<AccordionGroup>
<Accordion title="Fehlerbehebung bei Verbindungsproblemen">
- **Firewall blockiert**: Stellen Sie sicher, dass die Ports 80 und 443 geöffnet sind
- **Proxy-Konfiguration**: Setzen Sie die Umgebungsvariable HTTP_PROXY
- **DNS-Auflösung**: Versuchen Sie, 8.8.8.8 als DNS-Server zu verwenden
</Accordion>
<Accordion title="Erweiterte Konfiguration">
```javascript
const config = {
performance: { cache: true, timeout: 30000 },
security: { encryption: 'AES-256' }
};
```
</Accordion>
</AccordionGroup>
### Karten und Spalten zur Hervorhebung von Informationen
Beispiel für Karten und Kartengruppen:
<Card title="Einstiegshandbuch" icon="rocket" href="/quickstart">
Komplette Schritt-für-Schritt-Anleitung von der Installation bis zu Ihrem ersten API-Aufruf in unter 10 Minuten.
</Card>
<CardGroup cols={2}>
<Card title="Authentifizierung" icon="key" href="/auth">
Erfahren Sie, wie Sie Anfragen mit API-Schlüsseln oder JWT-Token authentifizieren.
</Card>
<Card title="Ratenbegrenzung" icon="clock" href="/rate-limits">
Verstehen Sie Ratenlimits und Best Practices für die Nutzung mit hohem Volumen.
</Card>
</CardGroup>
### Komponenten für API-Dokumentation
#### Parameterfelder
Beispiel für Parameterdokumentation:
<ParamField path="user_id" type="string" required>
Eindeutiger Bezeichner für den Nutzer. Muss dem gültigen UUID-v4-Format entsprechen.
</ParamField>
<ParamField body="email" type="string" required>
E-Mail-Adresse des Nutzers. Muss gültig und innerhalb des Systems eindeutig sein.
</ParamField>
<ParamField query="limit" type="integer" default="10">
Maximale Anzahl der zurückzugebenden Ergebnisse. Bereich: 1–100.
</ParamField>
<ParamField header="Authorization" type="string" required>
Bearer-Token für die API-Authentifizierung. Format: `Bearer YOUR_API_KEY`
</ParamField>
#### Response-Felder
Beispiel für Response-Felddokumentation:
<ResponseField name="user_id" type="string" required>
Eindeutiger Bezeichner, der dem neu erstellten Nutzer zugewiesen wurde.
</ResponseField>
<ResponseField name="created_at" type="timestamp">
Zeitstempel im ISO-8601-Format, zu dem der Nutzer erstellt wurde.
</ResponseField>
<ResponseField name="permissions" type="array">
Liste von Berechtigungs-Strings, die diesem Nutzer zugewiesen sind.
</ResponseField>
#### Erweiterbare verschachtelte Felder
Beispiel für die Dokumentation verschachtelter Felder:
<ResponseField name="user" type="object">
Vollständiges Nutzerobjekt mit allen zugehörigen Daten.
<Expandable title="Nutzereigenschaften">
<ResponseField name="profile" type="object">
Informationen zum Nutzerprofil einschließlich persönlicher Details.
<Expandable title="Profildetails">
<ResponseField name="first_name" type="string">
Vorname des Nutzers, wie bei der Registrierung angegeben.
</ResponseField>
<ResponseField name="avatar_url" type="string | null">
URL zum Profilbild des Nutzers. Gibt null zurück, wenn kein Avatar gesetzt ist.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
### Medien- und erweiterte Komponenten
#### Rahmen für Bilder
Fassen Sie alle Bilder in Rahmen:
<Frame>
<img src="/images/dashboard.png" alt="Haupt-Dashboard mit Analyseübersicht" />
</Frame>
<Frame caption="Das Analytics-Dashboard bietet Echtzeit-Einblicke">
<img src="/images/analytics.png" alt="Analytics-Dashboard mit Diagrammen" />
</Frame>
#### Videos
Verwenden Sie das HTML-Video-Element für selbst gehostete Videoinhalte:
<video
controls
className="w-full aspect-video rounded-xl"
src="link-to-your-video.com"
></video>
YouTube-Videos mithilfe von iframe-Elementen einbetten:
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/4KzFe50RQkQ"
title="YouTube-Videoplayer"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
#### Tooltips
Beispiel für die Verwendung von Tooltips:
<Tooltip tip="Application Programming Interface – Protokolle für die Softwareerstellung">
API
</Tooltip>
#### Updates
Verwenden Sie Updates für Changelogs:
<Update label="Version 2.1.0" description="Veröffentlicht am 15. März 2024">
## Neue Funktionen
- Funktion für Massenimport von Nutzern hinzugefügt
- Verbesserte Fehlermeldungen mit umsetzbaren Vorschlägen
## Fehlerbehebungen
- Paginierungsproblem bei großen Datensätzen behoben
- Probleme mit Authentifizierungs-Timeouts gelöst
</Update>
## Erforderliche Seitenstruktur
Jede Dokumentationsseite muss mit YAML-Frontmatter beginnen:
```yaml
---
title: "Klarer, spezifischer, schlüsselwortreicher Titel"
description: "Prägnante Beschreibung, die Zweck und Mehrwert der Seite erklärt"
---
```
## Standards für Inhaltsqualität
### Anforderungen an Codebeispiele
- Fügen Sie stets vollständige, ausführbare Beispiele bei, die Nutzer kopieren und ausführen können
- Zeigen Sie ordnungsgemäße Fehlerbehandlung und Umgang mit Randfällen
- Verwenden Sie realistische Daten statt Platzhalterwerten
- Fügen Sie erwartete Ausgaben und Ergebnisse zur Verifikation hinzu
- Testen Sie alle Codebeispiele gründlich vor der Veröffentlichung
- Geben Sie die Sprache an und fügen Sie bei Bedarf den Dateinamen hinzu
- Ergänzen Sie erklärende Kommentare für komplexe Logik
- Niemals echte API-Schlüssel oder Secrets in Codebeispielen verwenden
### Anforderungen an API-Dokumentation
- Dokumentieren Sie alle Parameter, einschließlich optionaler, mit klaren Beschreibungen
- Zeigen Sie sowohl Erfolgs- als auch Fehler-Response-Beispiele mit realistischen Daten
- Fügen Sie Informationen zur Ratenbegrenzung mit konkreten Limits hinzu
- Geben Sie Authentifizierungsbeispiele im korrekten Format an
- Erklären Sie alle HTTP-Statuscodes und die Fehlerbehandlung
- Decken Sie vollständige Request-/Response-Zyklen ab
### Anforderungen an Barrierefreiheit
- Fügen Sie beschreibenden Alt-Text für alle Bilder und Diagramme hinzu
- Verwenden Sie spezifischen, handlungsorientierten Linktext statt „hier klicken“
- Stellen Sie eine korrekte Überschriftenhierarchie beginnend mit H2 sicher
- Berücksichtigen Sie Tastaturnavigation
- Verwenden Sie ausreichenden Farbkontrast in Beispielen und Visuals
- Strukturieren Sie Inhalte für einfaches Scannen mit Überschriften und Listen
## Logik zur Komponentenauswahl
- Verwenden Sie **Steps** für Verfahren und sequentielle Anleitungen
- Verwenden Sie **Tabs** für plattformspezifische Inhalte oder alternative Ansätze
- Verwenden Sie **CodeGroup**, wenn dasselbe Konzept in mehreren Programmiersprachen gezeigt wird
- Verwenden Sie **Accordions** für die progressive Offenlegung von Informationen
- Verwenden Sie **RequestExample/ResponseExample** speziell für die Dokumentation von API-Endpunkten
- Verwenden Sie **ParamField** für API-Parameter, **ResponseField** für API-Antworten
- Verwenden Sie **Expandable** für verschachtelte Objekteigenschaften oder hierarchische Informationen