Verzeichnisstruktur

Diese Seite zeigt, wie Sie die Dateien in einem Jamdesk-Dokumentations-Repository organisieren – von der minimalen Struktur mit zwei Dateien bis zu einem vollständigen Layout mit mehreren Verzeichnissen.

Minimale Struktur

Ein einfaches Jamdesk-Projekt benötigt nur zwei Dateien:

my-docs/
├── docs.json           # Configuration
└── introduction.mdx    # Your first page

Empfohlene Struktur

Bei größeren Dokumentationswebsites organisieren Sie Seiten in Verzeichnissen:

my-docs/
├── docs.json
├── introduction.mdx
├── quickstart.mdx
│
├── guides/
│   ├── getting-started.mdx
│   ├── authentication.mdx
│   └── deployment.mdx
│
├── api-reference/
│   ├── overview.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   └── projects.mdx
│   └── webhooks.mdx
│
├── images/
│   ├── logo.svg
│   ├── favicon.svg
│   └── screenshots/
│       └── dashboard.png
│
└── snippets/
    └── api-base-url.mdx

Erforderliche Dateien

docs.json

Die Konfigurationsdatei, die Ihre Website definiert. Sie muss sich im Stammverzeichnis Ihres Dokumentationsverzeichnisses befinden (oder am in den Projekteinstellungen angegebenen Pfad).

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Documentation",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}

Eine Übersicht über alle Optionen finden Sie in der Referenz zu docs.json.

Seitenorganisation

Flach oder verschachtelt

Wählen Sie abhängig vom Umfang Ihrer Dokumentation:

docs/
├── docs.json
├── introduction.mdx
├── installation.mdx
├── configuration.mdx
└── troubleshooting.mdx

"pages": ["introduction", "installation"]

Namenskonventionen

Besondere Verzeichnisse

images/

Speichern Sie Bilder, Logos und Favicons:

images/
├── logo-light.webp     # Light mode logo
├── logo-dark.webp      # Dark mode logo
├── favicon.svg         # Browser favicon
└── screenshots/        # Documentation screenshots
    └── dashboard.png

Verweisen Sie in docs.json darauf:

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "favicon": "/images/favicon.svg"
}

snippets/

Wiederverwendbare Inhaltsblöcke:

snippets/
├── api-base-url.mdx
└── auth-header.mdx

Binden Sie sie in Seiten ein:

<Snippet file="api-base-url.mdx" />

openapi/

OpenAPI-Spezifikationsdateien für API-Dokumentation:

openapi/
├── api.yaml
└── webhooks.yaml

Verweisen Sie in docs.json darauf:

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Ein Live-Beispiel finden Sie unter OpenAPI-Beispiel.

Sprachspezifische Spezifikationsdateien

Fügen Sie bei mehrsprachigen Dokumentationswebsites übersetzte Spezifikationsdateien neben der Quelldatei mit einem Sprachcode-Infix hinzu:

openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml

Jamdesk stellt automatisch die richtige Spezifikation bereit, wenn eine Seite unter einem Sprachpräfix (/fr/…, /es/… usw.) gerendert wird. Die vollständigen Regeln dazu, was übersetzt werden muss und was identisch bleiben soll, finden Sie unter Mehrsprachige Unterstützung → OpenAPI-Spezifikationen übersetzen.

Zu ignorierende Dateien

Erstellen Sie eine .gitignore, um Build-Artefakte auszuschließen:

.jamdesk/
node_modules/
.DS_Store
*.log

Das Verzeichnis .jamdesk/ enthält den lokalen Entwicklungs-Cache und sollte nicht in das Repository übernommen werden.

Wie geht es weiter?