obsidian-publish-confluence

Publish Obsidian-flavored Markdown to Confluence over Kerberos.

Versioning is derived from Git tags for releases.

Features

• Create or update Confluence pages from Markdown.
• Store the Confluence page URL in note frontmatter.
• Upload attachments on both page create and update.
• Convert Obsidian image embeds like ![[image.png]] and ![[image.png|400]].
• Convert Obsidian Canvas embeds like ![[board.canvas]] to SVG attachments while preserving node coordinates and multiline labels.
• Convert Markdown checkbox lists into Confluence tasks, including nested unordered and ordered lists.
• Convert fenced code blocks to Confluence code macros.
• Convert PlantUML blocks to the native Confluence plantuml macro.
• Support --dry-run to inspect conversion and publish actions without changing Confluence.

Requirements

• Python 3.10+
• curl
• kinit and klist
• A Confluence instance that accepts Kerberos auth via curl --negotiate

Installation

pip install obsidian-publish-confluence

For local development:

python -m pip install -e .

Configuration

Set these environment variables:

• OBSIDIAN_PUBLISH_CONFLUENCE_BASE_URL
• OBSIDIAN_PUBLISH_CONFLUENCE_SPACE
• OBSIDIAN_PUBLISH_CONFLUENCE_PARENT_ID

Usage

export OBSIDIAN_PUBLISH_CONFLUENCE_BASE_URL="https://confluence.example.com"
export OBSIDIAN_PUBLISH_CONFLUENCE_SPACE="DOCS"
export OBSIDIAN_PUBLISH_CONFLUENCE_PARENT_ID="123456"

obsidian-publish-confluence note.md
obsidian-publish-confluence note.md --title "Custom title"
obsidian-publish-confluence note.md --page-url "https://confluence.example.com/spaces/DOCS/pages/123456"
obsidian-publish-confluence note.md --space DEV --parent-id 987654
obsidian-publish-confluence note.md --dry-run

--dry-run converts the note, prints the intended action and attachment list, and skips Confluence API calls.

The Confluence page URL is stored in the note frontmatter as confluence_url. An explicit --page-url takes precedence and is saved to the note after a successful publish.

Kerberos

The CLI expects a valid Kerberos ticket:

kinit YOUR_LOGIN@REALM.EXAMPLE

PlantUML

PlantUML fenced blocks are converted to the native Confluence plantuml macro.

This requires a Confluence instance with a compatible plantuml macro installed.

Release versioning

The package version comes from the Git tag used for the release. For PyPI releases, create a tag like v0.1.0 before publishing a GitHub Release. The release workflow verifies that the tag and built package version match.

Limitations

• Image and Canvas Obsidian embeds are converted to Confluence attachments; local images are resolved relative to the note and recursively in the vault.
• Canvas embeds are rendered as SVG with text, file, link, group, and edge data; embedded files and multiline labels are shown as labels.
• Checkbox task status is stored in Confluence task macros; nested tasks become nested task lists.
• Attachment names are namespaced automatically to avoid collisions between files with the same basename.
• Numeric Obsidian image suffixes like ![[image.png|640]] become Confluence image widths.
• Non-image wiki links stay plain text.
• PDF embeds are not converted.
• Auth mode is Kerberos-only.
• If a note has no confluence_url and --page-url is not provided, a new Confluence page is created.
• PlantUML publishing depends on the Confluence-side plantuml macro being available.

Publishing

This repository includes GitHub Actions for:

• building distributions on push and pull request
• publishing to PyPI on GitHub Release published

PyPI publishing is configured for Trusted Publishing.