Using markdown-confluence CLI to Sync Markdown into Confluence

I have been managing development decisions such as ADRs as Markdown files inside a docs directory in the Git repository.

But if non-developers also need to understand the history and context, leaving everything only in the repository is not enough. While looking for an alternative, I ended up at @markdown-confluence/cli.

Alternatives I considered or tried

Publish with Astro or something similar on S3

This would have been fine for me personally because frontend is my main area, but I decided against it because people with little frontend experience would have a hard time maintaining it over time.

Related to that, this kind of solution becomes obsolete quickly unless someone keeps updating versions and maintaining it continuously.

Write directly in Confluence from the start

You lose the ability to quickly view docs inside the local repository
Context gets split between the repository and Confluence, which makes moving around annoying
I simply do not like the Confluence editor very much

Syncing with `@markdown-confluence/cli`

It covers the main Markdown features
It can upload images as well
It can preserve the folder structure during upload
There seems to be an Obsidian plugin too, so it should work well for Obsidian users

What you need

The ID of the folder page to sync into
- Markdown files will be synced under the page specified here
ATLASSIAN_API_TOKEN
Your Confluence base URL, for example https://example.atlassian.net

Directory structure

If a .obsidian directory exists, it is excluded from deployment, but dot-prefixed directories or Markdown files are otherwise deployed as-is, so be careful.

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

Configuration

Manage configuration in .markdown-confluence.json.

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

confluenceBaseUrl: base URL of the destination Confluence
confluenceParentId: parent page ID on the destination Confluence
atlassianUserName: Atlassian account username
folderToPublish: path of the folder to publish, default is . (root)
firstHeadingPageTitle: whether # Heading1 becomes the page title

Deploy / upload

export ATLASSIAN_API_TOKEN=""

npx @markdown-confluence/cli

Writing and publishing behavior

Draft / private pages

---
connie-publish: false
---

# this is draft

What happens if you delete a file that has already been published?

It is not removed automatically, so you need to delete it manually on the Confluence side.

How to express WikiLinks

If you write links in the form [[markdown filename]], they are converted into links. Do not add the file extension.

If you use Obsidian, this usually works naturally without extra effort.

# title

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

Summary

With @markdown-confluence/cli, you can sync Markdown documentation from a Git repository into Confluence while still letting developers keep editing Markdown in their own editor.

Non-developers can read it in Confluence, while developers keep a Git-managed source of truth. It is a good middle ground that satisfies both sides.