Sincronizando Markdown com o Confluence usando markdown-confluence CLI

Eu vinha gerenciando decisões ligadas ao desenvolvimento, como ADRs, em arquivos Markdown dentro do diretório docs do repositório Git.

Mas, se pessoas não técnicas também precisam entender o histórico e o contexto, deixar tudo apenas no repositório não basta. Foi procurando uma alternativa que encontrei o @markdown-confluence/cli.

Alternativas que considerei ou testei

Publicar no S3 com Astro ou algo parecido

Para mim isso não seria um problema, porque frontend é minha área principal. Mesmo assim, descartei essa opção porque pessoas com pouca experiência em frontend teriam dificuldade para manter a solução no longo prazo.

Relacionado a isso, esse tipo de solução envelhece rápido se ninguém assumir a manutenção contínua e as atualizações de versão.

Escrever direto no Confluence desde o começo

Você perde a possibilidade de consultar rapidamente os documentos no repositório local
O contexto fica dividido entre o repositório e o Confluence, o que torna a navegação incômoda
E, de forma bem simples, eu não gosto muito do editor do Confluence

Sincronizando com `@markdown-confluence/cli`

Cobre a maior parte da sintaxe básica de Markdown
Também consegue enviar imagens
Mantém a estrutura de pastas durante o upload
Parece existir um plugin para Obsidian, então também deve funcionar bem para quem usa Obsidian

O que é necessário

O ID da página-pasta que servirá como destino da sincronização
- Os arquivos Markdown serão sincronizados abaixo da página indicada aqui
ATLASSIAN_API_TOKEN
A URL base da sua instância do Confluence, por exemplo https://example.atlassian.net

Estrutura de diretórios

Se existir um diretório .obsidian, ele será excluído do deploy. Já outros diretórios ou arquivos Markdown que começam com ponto serão publicados normalmente, então é bom tomar cuidado.

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

Configuração

A configuração fica em .markdown-confluence.json.

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

confluenceBaseUrl: URL base do Confluence de destino
confluenceParentId: ID da página pai no Confluence de destino
atlassianUserName: nome de usuário da conta Atlassian
folderToPublish: caminho da pasta a publicar, o padrão é . (raiz)
firstHeadingPageTitle: define se # Heading1 deve virar o título da página

Deploy / upload

export ATLASSIAN_API_TOKEN=""

npx @markdown-confluence/cli

Escrita e comportamento de publicação

Rascunho / não publicar

---
connie-publish: false
---

# this is draft

O que acontece se eu apagar um arquivo já publicado?

Ele não é removido automaticamente. É preciso apagá-lo manualmente no Confluence.

Como representar WikiLinks

Se você escrever [[nome-do-arquivo-markdown]], isso será convertido em link. Não inclua a extensão do arquivo.

Se você usa Obsidian, isso normalmente funciona de forma natural.

# title

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

Resumo

Com @markdown-confluence/cli, dá para sincronizar documentos Markdown de um repositório Git com o Confluence e, ao mesmo tempo, permitir que desenvolvedores continuem editando Markdown no editor que já usam.

Pessoas não técnicas podem ler no Confluence, enquanto desenvolvedores mantêm uma fonte de verdade confiável e versionada no Git. É um bom meio-termo para atender os dois lados.