Zum Inhalt springen
DDocsello
Suchen…Ctrl K

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:

[
  { "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, Abschnitt „Ordner-Aufbau“). Links zwischen Seiten schreibst du als [Text](page:kuerzel) oder [Text](page: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

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

GitHub Actions

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

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.

War diese Seite hilfreich?Aktualisiert am 3. Oktober 2026