Markdown mit markdown-confluence CLI nach Confluence synchronisieren

Ich habe entwicklungsbezogene Entscheidungen wie ADRs bislang als Markdown-Dateien im docs-Verzeichnis des Git-Repositories verwaltet.

Wenn aber auch Nicht-Entwicklerinnen und Nicht-Entwickler die Hintergründe verstehen sollen, reicht es nicht, alles nur im Repository liegen zu lassen. Bei der Suche nach einer Alternative bin ich auf @markdown-confluence/cli gestoßen.

Alternativen, die ich geprüft oder ausprobiert habe

Mit Astro oder Ähnlichem auf S3 veröffentlichen

Für mich persönlich wäre das kein Problem gewesen, weil Frontend mein Hauptgebiet ist. Ich habe mich trotzdem dagegen entschieden, weil Menschen mit wenig Frontend-Erfahrung so eine Lösung auf Dauer schwer warten können.

Außerdem veraltet so ein Ansatz schnell, wenn sich niemand dauerhaft um Updates und Pflege kümmert.

Von Anfang an direkt in Confluence schreiben

Man verliert die Möglichkeit, Dokumente schnell im lokalen Repository anzusehen
Der Kontext verteilt sich zwischen Repository und Confluence, was Wechsel zwischen beiden mühsam macht
Und ganz einfach: Ich mag den Confluence-Editor nicht besonders

Mit `@markdown-confluence/cli` synchronisieren

Die wichtigsten Markdown-Funktionen werden abgedeckt
Bilder lassen sich ebenfalls hochladen
Die Ordnerstruktur bleibt beim Upload erhalten
Es scheint auch ein Plugin für Obsidian zu geben, daher dürfte es auch für Obsidian-Nutzerinnen und -Nutzer gut passen

Was man dafür braucht

Die ID der Ziel-Ordnerseite
- Unter dieser Seite werden die Markdown-Dateien synchronisiert
ATLASSIAN_API_TOKEN
Die eigene Confluence-Basis-URL, zum Beispiel https://example.atlassian.net

Verzeichnisstruktur

Wenn ein .obsidian-Verzeichnis vorhanden ist, wird es vom Deployment ausgeschlossen. Andere punktpräfixierte Verzeichnisse oder Markdown-Dateien werden jedoch normal mitveröffentlicht, also Vorsicht.

.
└── root/
    ├── docs/
    │   ├── .hidden-dir
    │   ├── foo.md
    │   └── bar/
    │       └── baz.md
    ├── src
    ├── .markdown-confluence.json
    ├── package.json
    └── README.md

Konfiguration

Die Konfiguration liegt in .markdown-confluence.json.

{
  "confluenceBaseUrl": "https://example.atlassian.net",
  "confluenceParentId": "12345678",
  "atlassianUserName": "username@example.com",
  "folderToPublish": "path/to/folder",
  "firstHeadingPageTitle": true
}

confluenceBaseUrl: Basis-URL des Ziel-Confluence
confluenceParentId: Parent-Page-ID im Ziel-Confluence
atlassianUserName: Benutzername des Atlassian-Kontos
folderToPublish: Pfad des zu veröffentlichenden Ordners, Standard ist . (Root)
firstHeadingPageTitle: ob # Heading1 als Seitentitel verwendet werden soll

Deployment / Upload

export ATLASSIAN_API_TOKEN=""

npx @markdown-confluence/cli

Schreibweise und Veröffentlichungsverhalten

Entwurf / nicht veröffentlichen

---
connie-publish: false
---

# this is draft

Was passiert, wenn man eine bereits veröffentlichte Datei löscht?

Sie wird nicht automatisch entfernt. Man muss sie in Confluence manuell löschen.

Wie lassen sich WikiLinks ausdrücken?

Wenn man [[markdown-dateiname]] schreibt, wird das in einen Link umgewandelt. Die Dateiendung wird dabei nicht angegeben.

Wer Obsidian nutzt, kann das in der Regel ohne zusätzlichen Aufwand verwenden.

# title

- [[markdown-filename]]
- [[markdown-filename|Alias]]
- [[markdown-filename#Heading]]

Zusammenfassung

Mit @markdown-confluence/cli lässt sich Markdown-Dokumentation aus einem Git-Repository nach Confluence synchronisieren, während Entwicklerinnen und Entwickler weiterhin Markdown im gewohnten Editor schreiben können.

Nicht-Entwickler können die Inhalte in Confluence lesen, während Entwickler eine Git-verwaltete, verlässliche Quelle behalten. Das ist ein sinnvoller Mittelweg zwischen beiden Anforderungen.