Confluence Page Publisher

Obsidian plugin that publishes your notes to Confluence as Confluence Storage XHTML, with frontmatter page binding, attachment uploads, diagram rendering, automatic bound-note links, and content-hash based skips.

Install

From Obsidian

When the plugin is listed in the Obsidian community plugin browser:

Settings > Community plugins > Browse > Search Confluence Page Publisher > Install > Enable

Manual

1. Download main.js, manifest.json, and styles.css from the latest release

2. Create folder:

   /path/to/your-vault/.obsidian/plugins/confluence-page-publisher/
   

3. Copy the 3 files into that folder

4. Restart Obsidian

5. Settings > Community plugins > Enable "Confluence Page Publisher"

BRAT

1. Install BRAT

2. Open BRAT settings

3. Add beta plugin:

   gibranbadrul/obsidian-confluence-page
   

4. Enable "Confluence Page Publisher"

Usage

Bind a note to a Confluence page with frontmatter:

---
confluence_url: "https://example.atlassian.net/wiki/spaces/DOC/pages/123456/My+Page"
---

Then publish it:

Command Palette > Publish current note

The plugin converts the note to Confluence Storage XHTML, uploads local attachments, updates the Confluence page, and writes publish metadata back to the note.

After a successful publishing, the note frontmatter will look like this:

---
confluence_url: "https://example.atlassian.net/wiki/spaces/DOC/pages/123456/My+Page"
confluence_page_id: "123456"
confluence_last_published_at: "2026-07-07T10:30:00.000Z"
confluence_content_hash: "d3f91cb44f6c8a6d72c640adbc18e870f1aa0031"
confluence_attachments:
  "123456":
    image.png:
      hash: "38ab93050f81a0c93d8166150ed8540a47f2748d"
      id: "att987654"
---

Create a new child page

Use confluence_parent_url when the note should create a new page under an existing Confluence container.

Parent page example:

---
confluence_url:
confluence_parent_url: "https://example.atlassian.net/wiki/spaces/DOC/pages/100/Parent+Page"
confluence_title: "New Child Page"
---

On Confluence Cloud, the parent may also be a folder URL:

---
confluence_url:
confluence_parent_url: "https://example.atlassian.net/wiki/spaces/DOC/folder/200/Documentation"
confluence_title: "New Folder Page"
---

For a parent page, the plugin creates the new page directly beneath that page. For a Cloud folder, it creates the page in the folder's space and then moves it into the folder.

Folder parent URLs are supported only when Confluence type is set to Cloud. Confluence Server / Data Center requires a parent page URL.

After the first successful creation, the plugin writes the resolved page URL and ID into the note. Future publishes update that same page directly.

Trigger publishing

Helper commands

Frontmatter

Existing page

---
confluence_url: "https://example.atlassian.net/wiki/spaces/DOC/pages/123456/My+Page"
---

New child page

---
confluence_url:
confluence_parent_url: "https://example.atlassian.net/wiki/spaces/DOC/pages/100/Parent+Page"
---

Full template

---
confluence_url:
confluence_parent_url:
confluence_title:
confluence_page_id:
confluence_last_published_at:
confluence_content_hash:
---

The attachment cache is grouped by Confluence page ID so attachment metadata is not reused accidentally when the note is rebound to another page. Existing flat attachment metadata is migrated when a target page ID is available.

Creating a root page directly from a space key is planned. New pages currently require an existing parent page, or a folder when using Confluence Cloud.

What gets converted

Not converted yet

Internal macros

Confluence Page Publisher supports a few internal comment macros. These macros are only used by the plugin before publishing. They are not sent to Confluence.

Attachment publishing

When local attachment uploads are enabled, the publisher:

1. Resolves local Markdown images and Obsidian embeds from the vault
2. Calculates a content hash for each attachment
3. Reuses unchanged attachment metadata from confluence_attachments
4. Updates changed attachments using the cached attachment ID when possible
5. Falls back to filename lookup and Confluence's create-or-update endpoint when the direct update fails

Common image formats, including SVG (image/svg+xml), are supported. The fallback update flow is useful for Confluence instances that reject a direct attachment-data update for some file types.

Attachment filenames must be unique within a published page because Confluence addresses page attachments by filename.

Diagram rendering

Mermaid and PlantUML rendering is optional.

Default render services:

For private documentation, use a self-hosted Kroki or PlantUML service.

Settings

Settings > Community plugins > Confluence Page Publisher > Settings

Authentication

Changes to the base URL, Confluence type, authentication type, account, or selected key-vault secret are applied to the publisher connection without requiring an Obsidian restart. Use Validate credentials after changing connection settings.

Atlassian Cloud

Use Basic auth:

Account: your Atlassian email
Password / API token: Atlassian API token

Base URL usually looks like this:

https://example.atlassian.net/wiki

Confluence Server / Data Center with PAT

Use Bearer auth:

Password / API token: Personal Access Token

Base URL usually looks like this:

https://confluence.your-company.com

Legacy Server account

Use Basic auth:

Account: your username
Password / API token: your account password

Storage preview

Use this command to inspect the generated Confluence Storage XHTML before publishing:

Command Palette > Export storage preview of current note

It writes:

example.preview.xml

Use this when:

• A page does not render as expected in Confluence
• An attachment does not appear
• A callout or code block looks wrong
• Mermaid or PlantUML falls back to source text
• You want to debug the converter without updating Confluence

Privacy & network behavior

Confluence Page Publisher is a local Obsidian desktop plugin.

Here is what it does:

• Reads selected notes from your vault. Only notes you publish, or notes inside a folder/all-bound publish operation, are processed.
• Reads referenced local attachments. Local images and embeds are read so they can be uploaded to Confluence.
• Sends content to your configured Confluence URL. Page content, page metadata, and attachments are sent to Confluence when you publish.
• Uses your configured authentication method. Credentials are used only for Confluence API requests.
• Uses Obsidian key vault when available. Tokens should be stored as Obsidian secrets instead of plain text.
• May contact diagram render services. Mermaid and PlantUML source is sent to the configured render service only when diagram rendering is enabled.
• Does not read your clipboard. Publishing does not depend on clipboard access.
• Does not sync Confluence back into Obsidian. The flow is one-way: Obsidian to Confluence.
• Enumerates vault file paths when needed. The plugin scans Markdown files to find notes with Confluence publishing frontmatter for publish-all and folder publishing. It may also enumerate files as a fallback when resolving local attachment links by filename.

Limitations

• One-way publishing only
• Confluence edits are not pulled back into Obsidian
• New page creation requires an existing parent page URL, or a folder URL on Confluence Cloud
• Root page creation from confluence_space_key is planned
• Task lists, footnotes, math, tags-to-labels, note transclusion, and semantic image captions are planned
• Raw HTML is not executed
• Mobile Obsidian is not supported

Development

Prerequisites

• Bun
• Git-cliff

Setup

git clone https://github.com/gibranbadrul/obsidian-confluence-page.git
cd obsidian-confluence-page
bun install

Available targets

Run:

make help

The main targets are:

Build

make build

The build must produce:

dist/main.js
dist/manifest.json
dist/styles.css

Development build

make dev

Quality checks

Run the complete local validation workflow:

make check

Individual checks are also available:

make lint
make test

Deploy to a local vault

Configure either the vault root:

make install OBSIDIAN_VAULT="/path/to/vault"

or the complete plugin directory:

make install \
  OBSIDIAN_PLUGIN_DIR="/path/to/vault/.obsidian/plugins/confluence-page-publisher"

The target builds the plugin and copies main.js, manifest.json, and styles.css into the destination. Restart Obsidian or reload the plugin after installation.

Uninstall from a local vault

Use the same destination variable used during installation:

make uninstall OBSIDIAN_VAULT="/path/to/vault"

Release

Use the release script with flags:

./scripts/release.sh --major
./scripts/release.sh --minor
./scripts/release.sh --patch
./scripts/release.sh --auto
./scripts/release.sh --version <semver>

Release candidate:

./scripts/release.sh --minor --rc

Example to push release commit and tag:

./scripts/release.sh --version <SEMVER> --push

The release workflow builds and attaches the required plugin files:

main.js
manifest.json
styles.css

License

MIT Zero Clause