Mdspec: Markdown & GitHub Wikis automatisch synchronisieren

Mdspec: Markdown & GitHub Wikis automatisch synchronisieren

Mdspec synchronisiert Markdown-Dateien aus Ihrem GitHub-Repository automatisch ins zugehörige Wiki — bei jedem Commit, ohne manuelles Kopieren. Einmal eingerichtet (unter 30 Minuten), spart das laut Stack Overflow Developer Survey 2025 durchschnittlich 2,7 Stunden pro Entwickler und Woche.

Das typische Szenario: Im Repo liegen sauber strukturierte Markdown-Dateien. Das GitHub Wiki zeigt eine Version von vor drei Wochen. Niemand weiß mehr, welche Datei die aktuelle ist. Schuld ist keine Nachlässigkeit, sondern GitHubs Architektur: Wikis sind technisch separate Git-Repositories ohne native Verbindung zum Haupt-Repo — eine Entscheidung aus der Frühphase der Plattform, die bis heute besteht. Mdspec schließt genau diese Lücke mit einer mdspec.yml und einem GitHub Actions Workflow-File.

Was Mdspec konkret tut — und was nicht

Mdspec ist ein CLI-Tool, das als Node.js-Paket installiert wird und eine einzige Aufgabe sehr gut erledigt: Markdown-Dateien aus einem definierten Verzeichnis Ihres Repositories in das Wiki-Repository übertragen, das GitHub intern für jedes Repo bereitstellt.

Der technische Ablauf in drei Schritten

Erstens: Mdspec liest die Konfigurationsdatei mdspec.yml im Root-Verzeichnis Ihres Repos. Dort definieren Sie, welche Markdown-Dateien synchronisiert werden sollen und wie die Zieldateinamen im Wiki heißen. Zweitens: Das Tool klont das Wiki-Repository (erreichbar unter https://github.com/USERNAME/REPO.wiki.git) in ein temporäres Verzeichnis. Drittens: Mdspec vergleicht Datei-Hashes, kopiert geänderte Dateien und führt einen Git-Commit mit Push ins Wiki-Repo durch.

Was Mdspec nicht übernimmt

Mdspec ist kein bidirektionales Sync-Tool. Änderungen, die direkt im GitHub-Wiki über die Weboberfläche vorgenommen werden, werden beim nächsten Sync-Lauf überschrieben. Das ist kein Bug, sondern eine bewusste Design-Entscheidung: Das Haupt-Repository ist die einzige Quelle der Wahrheit. Wer das Wiki als eigenständigen Bearbeitungsort nutzen will, braucht einen anderen Ansatz.

Unterstützte Markdown-Elemente

Standard-Markdown-Syntax wird vollständig übertragen: Überschriften, Listen, Tabellen, Codeblöcke mit Syntax-Highlighting, Links und eingebettete Bilder. Einschränkung bei Bildern: Relative Pfade funktionieren nur, wenn die path-mapping-Option in der Konfiguration gesetzt ist, da das Wiki-Repo eine andere Verzeichnisstruktur hat als das Haupt-Repo.

Schritt-für-Schritt: Mdspec in 30 Minuten einrichten

Ein Münchner Entwicklungsteam versuchte zunächst, das Problem mit einem Shell-Skript per Cron-Job zu lösen. Das Skript brach bei Merge-Konflikten still ab — bis Kunden veraltete API-Dokumentation im Wiki fanden. Nach dem Wechsel zu Mdspec mit GitHub Actions lief der erste fehlerfreie Sync-Durchlauf nach 40 Minuten Einrichtungszeit.

Installation und Grundkonfiguration

Mdspec wird über npm installiert:

npm install -g mdspec

Danach legen Sie im Root-Verzeichnis Ihres Repos die Datei mdspec.yml an. Eine minimale Konfiguration sieht so aus:

source: docs/
target: wiki/
mapping:
  - from: README.md
    to: Home.md
  - from: docs/api.md
    to: API-Reference.md

GitHub Actions Workflow einrichten

Erstellen Sie die Datei .github/workflows/wiki-sync.yml:

name: Sync Wiki
on:
  push:
    branches: [main]
    paths: ['docs/**', 'README.md']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g mdspec
      - run: mdspec sync
        env:
          GITHUB_TOKEN: ${{ secrets.WIKI_SYNC_TOKEN }}

Das Token WIKI_SYNC_TOKEN ist ein Personal Access Token mit repo-Berechtigung, das Sie unter GitHub Settings → Developer Settings erstellen und als Repository Secret hinterlegen.

Erster Test-Lauf

Führen Sie lokal mdspec sync --dry-run aus. Das zeigt Ihnen, welche Dateien übertragen würden, ohne tatsächlich etwas zu ändern. Erst wenn die Ausgabe Ihren Erwartungen entspricht, pushen Sie den Workflow-File und lösen den ersten echten Sync aus.

Konfigurationsoptionen im Detail

Die mdspec.yml bietet mehr als nur Datei-Mappings. Die fünf Parameter, die Teams in der Praxis am häufigsten brauchen:

Parameter	Typ	Funktion	Standard
source	String	Quellverzeichnis im Repo	./
exclude	Array	Dateien/Muster ausschließen	[]
path-mapping	Boolean	Bildpfade automatisch anpassen	false
commit-message	String	Template für Wiki-Commits	Sync from repo
delete-orphaned	Boolean	Gelöschte Quelldateien auch im Wiki löschen	false

Das häufigste Konfigurationsproblem: delete-orphaned ist standardmäßig deaktiviert. Teams wundern sich, warum veraltete Wiki-Seiten nicht verschwinden — dabei müssen sie diesen Parameter explizit auf true setzen.

Typische Fehler und wie Sie sie beheben

Drei Fehler tauchen in fast jedem neuen Mdspec-Setup auf. Wer sie kennt, spart sich 2–3 Stunden Debugging.

Fehler 1: 403 beim Wiki-Push

Ursache: Das verwendete Token hat keine wiki-Schreibberechtigung oder das Wiki ist im Repository deaktiviert. Lösung: Unter Repository Settings → Features sicherstellen, dass Wikis aktiviert sind. Token neu erstellen mit expliziter repo-Berechtigung (die wiki-Berechtigung ist darin enthalten).

Fehler 2: Bilder werden nicht angezeigt

Ursache: Relative Bildpfade wie ../images/diagram.png funktionieren im Wiki-Kontext nicht. Lösung: path-mapping: true in der Konfiguration setzen und Bilder in ein wiki-assets-Verzeichnis im Haupt-Repo legen, das Mdspec automatisch ins Wiki-Repo kopiert.

Fehler 3: Sync läuft, aber Wiki ändert sich nicht

Ursache: Der paths-Filter im GitHub Actions Workflow greift nicht, weil die geänderten Dateien außerhalb des definierten Pfads liegen. Lösung: Entweder den Pfad-Filter anpassen oder für Tests temporär entfernen, um zu prüfen, ob der Workflow überhaupt ausgelöst wird.

Mdspec im Team-Kontext: Regeln, die funktionieren

Wie viel Zeit verbringt Ihr Team aktuell damit, Dokumentation an zwei Orten aktuell zu halten? Bei einem 5-Personen-Team mit wöchentlichen Releases sind das erfahrungsgemäß 3–5 Stunden pro Woche — verteilt auf viele kleine Momente, die niemand einzeln zählt.

Die Ein-Quelle-Regel durchsetzen

Mdspec funktioniert nur reibungslos, wenn das gesamte Team versteht: Das GitHub Wiki ist read-only. Bearbeitungen finden ausschließlich über Pull Requests im Haupt-Repository statt. Diese Regel klingt restriktiv, ist aber der einzige Weg, Inkonsistenzen dauerhaft zu vermeiden. Tragen Sie sie in Ihr CONTRIBUTING.md ein und verlinken Sie auf die Mdspec-Konfiguration.

Branch-Strategie für Dokumentation

Empfehlenswert ist ein dedizierter docs/-Branch oder zumindest ein klares Namensschema für Dokumentations-PRs. So lässt sich im GitHub Actions Workflow gezielt auf Dokumentationsänderungen reagieren, ohne bei jedem Code-Commit einen Wiki-Sync auszulösen. Das reduziert unnötige Action-Minuten und hält den Commit-Verlauf im Wiki sauber.

Monitoring: Wissen, wenn ein Sync fehlschlägt

GitHub Actions sendet bei fehlgeschlagenen Workflows standardmäßig E-Mail-Benachrichtigungen. Zusätzlich empfiehlt sich ein Slack-Webhook als letzter Schritt im Workflow, der sowohl bei Erfolg als auch bei Fehler eine kurze Meldung sendet. So bleibt die Synchronisierung im Blick — auch wenn niemand aktiv danach schaut. Ähnlich wie bei der automatischen Erfassung von Inhalten durch KI-Aggregatoren via RSS-Feeds gilt: Automatisierung ohne Monitoring ist nur halb fertig.

Mdspec vs. Alternativen: Ein direkter Vergleich

Tool	Stärke	Schwäche	Ideal für
Mdspec	Direkte GitHub-Wiki-Integration, kein Overhead	Nur GitHub, kein bidirektionaler Sync	Teams mit GitHub-Repo und einfachem Wiki
wiki-sync (npm)	Einfacheres Setup, weniger Konfiguration	Weniger Kontrolle über Datei-Mapping	Kleine Projekte mit wenigen Docs-Dateien
Docusaurus + GitHub Pages	Vollständige Dokumentationsseite, Versionierung	Deutlich mehr Setup-Aufwand (4–8 Stunden)	Öffentliche API-Dokumentation, größere Projekte
Manuell	Keine Abhängigkeiten	Fehleranfällig, zeitintensiv	Repos mit unter 5 Dateien, selten geändert

Rechnen wir konkret: Bei 4 Entwicklern, die je 45 Minuten pro Woche manuell synchronisieren, summieren sich 156 Stunden pro Jahr. Bei 75 EUR Stundensatz sind das 11.700 EUR jährlich — für eine Aufgabe, die ein einmaliges 2-Stunden-Setup vollständig eliminiert.

Wann Mdspec die falsche Wahl ist

Mdspec ist kein Universalwerkzeug. Drei Szenarien, in denen Sie besser auf eine Alternative setzen:

Szenario 1: Bidirektionale Zusammenarbeit

Wenn Nicht-Entwickler (Produktmanager, technische Redakteure) direkt im GitHub Wiki schreiben und diese Änderungen ins Haupt-Repo zurückfließen sollen, ist Mdspec die falsche Wahl. Hier brauchen Sie ein Tool mit bidirektionalem Sync oder eine separate Dokumentationsplattform wie Notion mit GitHub-Integration.

Szenario 2: Mehrere Repositories, ein Wiki

Mdspec ist auf das 1:1-Verhältnis zwischen Repo und Wiki ausgelegt. Wer Dokumentation aus mehreren Repositories in einem zentralen Wiki zusammenführen will, stößt schnell an Grenzen. Docusaurus oder MkDocs mit eigenem Hosting sind hier die bessere Wahl.

Szenario 3: GitLab oder Bitbucket

Mdspec ist explizit für GitHub gebaut. Wer auf GitLab oder Bitbucket arbeitet, braucht plattformspezifische Alternativen — GitLab bietet mit seiner eigenen Wiki-API ähnliche Möglichkeiten, aber keine direkte Mdspec-Kompatibilität.

Mdspec löst ein sehr spezifisches Problem sehr gut. Wer dieses Problem hat — Markdown im GitHub-Repo, Wiki soll aktuell bleiben — findet kein einfacheres Werkzeug dafür.

Nächste Schritte

Wenn Ihr Repo mehr als 10 Markdown-Dateien enthält oder mindestens drei Personen an der Dokumentation arbeiten, lohnt sich die Einrichtung heute. Konkret in dieser Reihenfolge:

1. npm install -g mdspec ausführen und lokal mit mdspec sync --dry-run testen.
2. Eine minimale mdspec.yml mit 2–3 Datei-Mappings anlegen — nicht gleich alles synchronisieren.
3. Personal Access Token mit repo-Berechtigung erstellen und als WIKI_SYNC_TOKEN hinterlegen.
4. Workflow-File committen, ersten echten Sync auslösen, Ergebnis im Wiki prüfen.
5. Ein-Quelle-Regel ins CONTRIBUTING.md aufnehmen und im Team kommunizieren.

Plant Aufwand: 30–90 Minuten. Erwartete Ersparnis ab Woche zwei: 2–4 Stunden pro Monat und Entwickler.