Confluence Markdown

Bidirectional Markdown-to-Confluence sync. Download pages as Markdown, publish and update them back with images and mermaid diagrams.

Features

• Download spaces, pages and page trees as Markdown with images

• Publish new Confluence pages from local Markdown files

• Update existing pages with version conflict detection

• Publish directory trees as page hierarchies

• Mermaid diagrams rendered to PNG and uploaded as attachments

• Local image upload as page attachments

• Dry-run by default for all write operations

• Multi-org support (override Confluence URL per request)

• YAML frontmatter for page tracking (ID, version, space)

• Full-width page layout applied automatically

• Homepage support (update space homepage from a markdown file)

Related MCP server: MCP Atlassian Node Server

Setup

1. Clone this repo

2. Install dependencies:

pip install -e .

3. Create a .env file in the project root:

CONFLUENCE_URL=https://your-site.atlassian.net
CONFLUENCE_EMAIL=you@example.com
CONFLUENCE_API_TOKEN=your-api-token

Generate tokens at id.atlassian.com. Token must be unscoped.

Project Config

Each project that publishes to Confluence needs a confluence.json:

{
  "space_key": "ECM",
  "confluence_url": "https://rebura.atlassian.net",
  "docs_dir": "Design Documents",
  "parent_page_id": "1915061323"
}

Usage

Sync a project (dry-run)

python -c "import sys; sys.path.insert(0, r'<path-to-this-repo>'); from confluence_markdown_mcp import sync_project; print(sync_project(r'<path-to-confluence.json>'))"

Sync a project (execute)

python -c "import sys; sys.path.insert(0, r'<path-to-this-repo>'); from confluence_markdown_mcp import sync_project; print(sync_project(r'<path-to-confluence.json>', confirm=True))"

Update a single page

python -c "import sys; sys.path.insert(0, r'<path-to-this-repo>'); from confluence_markdown_mcp import update_page; print(update_page(r'<path-to-file.md>', confirm=True))"

Publish a single new page

python -c "import sys; sys.path.insert(0, r'<path-to-this-repo>'); from confluence_markdown_mcp import publish_page; print(publish_page(r'<path-to-file.md>', confirm=True))"

Kiro Integration

A steering file is included at .kiro/steering/confluence-sync.md. Reference it with #confluence-sync in Kiro chat to enable conversational sync (e.g. "upload to confluence").

Frontmatter

Files track their Confluence state via YAML frontmatter:

---
title: "Page Title"
confluence_page_id: "123456"
confluence_space_key: "ECM"
confluence_version: 3
confluence_homepage: true
---

• confluence_homepage: true - updates the space's existing homepage content instead of creating a new page

• Files without confluence_page_id are created as new pages

• Files with confluence_page_id are updated in place

Mermaid Diagrams

Mermaid code blocks are automatically rendered to PNG (2x scale, white background) and uploaded as page attachments. The source mermaid stays in your local files.

Requires mmdc (Mermaid CLI): npm install -g @mermaid-js/mermaid-cli

License

MIT