Synchroniser du Markdown vers Confluence avec markdown-confluence CLI

Je gérais jusqu’ici les décisions liées au développement, comme les ADR, dans le répertoire docs du dépôt Git, sous forme de fichiers Markdown.

Mais si des personnes non techniques doivent elles aussi comprendre l’historique et le contexte, laisser ces documents uniquement dans le dépôt ne suffit pas. En cherchant une solution alternative, je suis tombé sur @markdown-confluence/cli.

Alternatives envisagées ou testées

Publier sur S3 avec Astro ou un outil similaire

Pour moi ce n’aurait pas posé de problème, car le frontend est mon domaine principal. En revanche, j’ai abandonné cette idée parce qu’une personne ayant peu d’expérience frontend aurait du mal à maintenir la solution dans la durée.

Dans la même logique, sans vraie discipline de maintenance et de mise à jour des versions, ce genre de solution se dégrade vite.

Écrire directement dans Confluence dès le départ

On perd la possibilité de consulter rapidement les documents dans le dépôt local
Le contexte se retrouve dispersé entre le dépôt et Confluence, ce qui rend les allers-retours pénibles
Et, tout simplement, je n’aime pas vraiment l’éditeur de Confluence

Synchroniser avec `@markdown-confluence/cli`

L’outil couvre l’essentiel de la syntaxe Markdown
Il peut aussi téléverser des images
Il conserve la structure des dossiers à l’envoi
Il semble aussi exister un plugin pour Obsidian, donc cela paraît adapté aux utilisateurs d’Obsidian

Ce qu’il faut

L’ID de la page dossier qui servira de destination
- Les fichiers Markdown seront synchronisés sous cette page
ATLASSIAN_API_TOKEN
L’URL de base de votre instance Confluence, par exemple https://example.atlassian.net

Structure de répertoire

Si un répertoire .obsidian existe, il est exclu du déploiement. En revanche, les autres dossiers ou fichiers Markdown commençant par un point sont publiés tels quels, donc il faut faire attention.

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

Configuration

La configuration se gère dans .markdown-confluence.json.

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

confluenceBaseUrl : URL de base du Confluence cible
confluenceParentId : ID de la page parente dans Confluence
atlassianUserName : nom d’utilisateur du compte Atlassian
folderToPublish : chemin du dossier à publier, . (racine) par défaut
firstHeadingPageTitle : indique si # Heading1 devient le titre de la page

Déploiement / envoi

export ATLASSIAN_API_TOKEN=""

npx @markdown-confluence/cli

Mode de rédaction et publication

Brouillon / non publié

---
connie-publish: false
---

# this is draft

Que se passe-t-il si l’on supprime un fichier déjà publié ?

Il n’est pas supprimé automatiquement. Il faut le retirer manuellement dans Confluence.

Comment représenter des WikiLinks

Si l’on écrit [[nom-du-fichier-markdown]], cela sera converti en lien. Il ne faut pas ajouter l’extension.

Si vous utilisez Obsidian, cela fonctionne généralement sans effort particulier.

# title

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

Liens

Résumé

Avec @markdown-confluence/cli, on peut synchroniser la documentation Markdown d’un dépôt Git vers Confluence tout en permettant aux développeurs de continuer à écrire en Markdown dans leur éditeur habituel.

Les non-développeurs peuvent lire dans Confluence, tandis que les développeurs conservent une source de vérité versionnée par Git. C’est un bon compromis pour répondre aux besoins des deux côtés.