Verzeichnisstruktur

Organisieren Sie die Dateien in einem Jamdesk-Dokumentations-Repository, vom minimalen Zwei-Dateien-Setup bis zu einem vollständigen Layout mit mehreren Verzeichnissen.

Minimale Struktur

Das einfachste Jamdesk-Projekt benötigt zwei Dateien:

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

Empfohlene Struktur

Für größere Dokumentationsseiten 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 Seite definiert. Sie muss im Stammverzeichnis Ihres Dokumentationsverzeichnisses liegen (oder im Pfad, der in den Projekteinstellungen angegeben ist).

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

Alle Optionen finden Sie in der docs.json-Referenz.

Seitenorganisation

Flach oder verschachtelt

Wählen Sie je nach 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

Referenzieren in docs.json:

{
  "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

Einbinden in Seiten:

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

openapi/

OpenAPI-Spezifikationsdateien für API-Dokumentation:

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

Referenzieren in docs.json:

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

Ein Live-Beispiel finden Sie unter OpenAPI-Beispiel.

Sprachspezifische Spezifikationsdateien

Für mehrsprachige Dokumentationsseiten fügen Sie übersetzte Spezifikationsdateien neben der Quelldatei mit einem Sprachcode-Infix hinzu:

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

Jamdesk liefert automatisch die richtige Spezifikation aus, wenn eine Seite unter einem Sprachpräfix (/fr/…, /es/… usw.) gerendert wird. Die vollständigen Regeln dazu, was übersetzt und was identisch belassen werden 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 Entwicklungscache. Committen Sie es nicht.

Wie geht es weiter?