Two-way Markdown ↔ Confluence sync from the command line, written in Python.
Confluence MD allows you to create, edit and download Confluence Cloud pages as local Markdown files — all through the REST API, with a single-file script and no server-side install. It works page by page or on whole page trees, mirroring them to local folders and back.
Round-tripping is the point: every supported element converts in both directions, so a page can be downloaded, edited locally in your editor, and pushed back without losing structure. A version marker in each downloaded file ensures nobody's concurrent edits are overwritten along the way.
- Three subcommands:
uploadcreates a page,editreplaces one,downloadsaves it as Markdown - Bidirectional conversion: headings, tables, lists, blockquotes, code and formatting round-trip
- Code language preserved: fenced blocks map to the Confluence
codemacro in both directions - Task lists:
- [ ]/- [x]become Confluence action items and back, checked state kept - Panels:
**Note:**-labeled blockquotes become Info/Note/Warning/Tip panels and back - Table of Contents:
[TOC]becomes the TOC macro on upload, anchor links on download - Child pages:
[CHILD_PAGES]becomes the Children macro on upload, page links on download - Images: local images upload as attachments; page images download into a folder next to the file
- Tree sync:
--recursiveuploads or downloads whole page trees as folders, links rewritten - Edit safety:
editrefuses to overwrite pages changed since your download, unless--force - Version history preserved: every update is a new page version, history never destroyed
- Collision safety:
uploadrefuses to shadow an existing page title and points you toedit - Zero infrastructure: one Python file, four pip dependencies, credentials in a local
.env
| Document | What it covers |
|---|---|
| Architecture | Module layout, the two pipelines, placeholders, version markers and tree sync |
| Configuration | Creating the API token, finding your base URL, and the .env file |
| Usage | The three subcommands, every argument, examples and the download–edit–push workflow |
| Conversion | Element-by-element Markdown ↔ Confluence equivalences, and known limitations |
| Troubleshooting | Symptom first: what each error means and how to fix it |
Contributions are welcome: CONTRIBUTING.md covers the PR workflow, commit style, local checks and project rules.
Security issues: see SECURITY.md for private reporting.