# Docs aus Git

> Eine komplette Dokumentation mit mehreren Bereichen und Changelog im Repository pflegen und per CI veröffentlichen.

Viele Teams schreiben Dokumentation neben dem Code, im selben Repository, und prüfen sie per Pull Request. Mit
`docsello sync` wird daraus bei jedem Push eine Docsello-Website – mit mehreren Bereichen und einem Changelog. Auch
diese Dokumentation hier entsteht so.

## Aufbau im Repository

```
content/
├── spaces.json
├── erste-schritte/
│   ├── 01-willkommen.md
│   └── 02-begriffe.md
└── inhalte/
    ├── 01-editor.md
    └── 02-bausteine.md
CHANGELOG.md
```

Die Datei `spaces.json` beschreibt die Bereiche – einer pro Ordner, dazu optional Changelog-Bereiche:

```json
[
  { "folder": "erste-schritte", "slug": "erste-schritte", "name": "Erste Schritte", "description": "…", "icon": "rocket", "visibility": "public" },
  { "folder": "inhalte", "slug": "inhalte", "name": "Inhalte schreiben", "icon": "book-open", "visibility": "public" },
  { "changelog": "../CHANGELOG.md", "slug": "neuigkeiten", "name": "Neuigkeiten", "icon": "megaphone", "visibility": "public", "titlePrefix": "Version " }
]
```

| Feld | Bedeutung |
|---|---|
| `folder` **oder** `changelog` | Ordner mit Markdown-Dateien bzw. Pfad zu einer `CHANGELOG.md` (relativ zu `content/`) |
| `slug` | Adresse des Bereichs – keine reservierten Adressen wie `api`, `admin`, `search` oder Sprachkürzel |
| `name`, `description` | Name und Beschreibung des Bereichs |
| `icon` | Symbolname aus der Symbolauswahl von Docsello, z. B. `rocket`, `book-open`, `lock`, `globe`, `code`, `server`, `megaphone` |
| `visibility` | `public`, `unlisted`, `password` oder `signin` |
| `titlePrefix` | Nur Changelog: Vorsatz für die Eintragstitel, z. B. `"Version "` |
| `locale` | Optional: Sprache des Bereichs (Standard `de`) |

Innerhalb der Ordner gelten die Regeln von `docsello push` (siehe [CLI](doc:cli), Abschnitt „Ordner-Aufbau“). Links
zwischen Seiten schreibst du als `[Text](page:kuerzel)` oder `[Text](doc:kuerzel)` – das Kürzel ist der Dateiname ohne
Nummer und Endung (`01-willkommen.md` → `willkommen`). Kürzel müssen deshalb über alle Bereiche eindeutig sein.

## Abgleichen

```bash
docsello sync content --dry-run          # nur prüfen und anzeigen
docsello sync content -m "$(git log -1 --pretty=%s)"
```

`sync` prüft zuerst den Inhalt und bricht bei Fehlern ab, bevor irgendetwas geändert wird:

- doppelte Bereichs- oder Seitenkürzel, reservierte Bereichsadressen, unbekannte Sichtbarkeiten,
- Links auf Seiten, die es nicht gibt,
- öffentliche Seiten, die auf Seiten in geschützten Bereichen verlinken.

Danach legt es fehlende Bereiche an (in der Reihenfolge der `spaces.json`), gleicht Name, Beschreibung, Symbol und
Sichtbarkeit bestehender Bereiche ab, lädt jeden Ordner hoch (veröffentlicht, Seiten ohne Datei wandern in den
Papierkorb) und importiert die Changelogs.

| Option | Bedeutung |
|---|---|
| `--dry-run` | Nichts ändern. Ohne `DOCSELLO_URL`/`DOCSELLO_TOKEN` wird nur der Inhalt geprüft |
| `--message`, `-m` | Notiz für den Verlauf |
| `--locale` | Sprache für neue Bereiche und Seiten (Standard `de`) |
| `--only <bereich>` | Nur diesen Bereich abgleichen |

:::info[Token-Rechte]
Ein Token mit **Bearbeiten & veröffentlichen** reicht für den Abgleich. Soll `sync` auch die Sichtbarkeit eines
bestehenden Bereichs ändern, braucht der Token **Admin (alles)** – oder du stellst die Sichtbarkeit einmal in der
Verwaltung um.
:::

## GitHub Actions

Ein Workflow, der bei Pull Requests nur prüft und auf `main` veröffentlicht:

```yaml
name: Docs
on:
  push:
    branches: [main]
    paths: ["content/**", "CHANGELOG.md"]
  pull_request:
    paths: ["content/**", "CHANGELOG.md"]
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      # die CLI aus dem neuesten Docsello-Release (siehe CLI → Installation)
      - name: CLI
        env:
          GH_TOKEN: ${{ secrets.DOCSELLO_REPO_TOKEN }}   # Lesezugriff auf Ceddini/docsello
        run: gh release download --repo Ceddini/docsello --pattern docsello.mjs
      - name: Check content
        run: node docsello.mjs sync content --dry-run
      - name: Publish
        if: github.event_name != 'pull_request' && vars.DOCSELLO_URL != ''
        env:
          DOCSELLO_URL: ${{ vars.DOCSELLO_URL }}
          DOCSELLO_TOKEN: ${{ secrets.DOCSELLO_TOKEN }}
          MESSAGE: ${{ github.event.head_commit.message || 'Docs sync' }}
        run: node docsello.mjs sync content -m "$MESSAGE"
```

Im Repository unter *Settings → Secrets and variables → Actions* legst du die Variable `DOCSELLO_URL` (z. B.
`https://docs.example.com`) und die Secrets `DOCSELLO_TOKEN` und `DOCSELLO_REPO_TOKEN` (GitHub-Token mit Lesezugriff
auf das Docsello-Repository, solange es privat ist) an.

:::tip[Andere Werkzeuge]
`sync` versteht dasselbe Format wie die Docs-Pipelines von Plazello und Cyrellian. Wer kein Node.js nutzen will,
spricht die [REST-API](doc:rest-api) direkt an (`POST /spaces`, `POST /spaces/{space}/import`,
`POST /spaces/{space}/changelog`).
:::