Confluence Vault Uploader

Sync your entire Obsidian vault to Confluence, preserving the folder structure as a page hierarchy. Obsidian wiki links become real Confluence page links, callout blocks become Confluence macros, and code blocks get syntax highlighting.

Features

• Full vault sync — every .md file becomes a Confluence page nested under the correct parent
• Folder pages — each folder is a Confluence page; files starting with _ (MOC files) supply its content
• Wiki link resolution — [[Page]], [[Folder/Page]], [[Page|Display Text]], and ![[Embed]] all become working Confluence links
• Callout conversion — Obsidian > [!note], > [!warning], > [!tip], > [!danger] etc. become Confluence info/warning/tip panels
• Code block macros — fenced code blocks with a language tag become Confluence code macros with syntax highlighting
• Two-phase sync — Phase 1 creates all pages; Phase 2 wires up every cross-page link so nothing is left broken
• Incremental updates — re-running only updates changed pages, preserving Confluence version history
• Live status — a status bar item always shows idle/syncing/last-result state; click it (or run Show Confluence sync status) for details
• Configurable logging — choose None/Normal/Verbose logging and inspect it any time with Show Confluence sync log, without opening the developer console
• Cache repair — Repair Confluence sync cache validates every cached page mapping and clears stale entries that cause 404 errors, queuing the affected files for re-sync

Installation

Not yet in Obsidian's official Community Plugins directory (submission pending). Use one of the methods below in the meantime.

Option A: BRAT (recommended — gets you real auto-updates)

Obsidian's built-in "Check for updates" only manages plugins installed through the official Community Plugins directory, so a manually installed copy of this plugin (Option B) will not auto-update. BRAT (Beta Reviewers Auto-update Tool) is a community plugin that installs and auto-updates plugins directly from their GitHub repo, without requiring the official listing — it works with this repo's releases as-is, with nothing special to configure.

1. Install BRAT from Obsidian's Community Plugins browser (Settings → Community plugins → Browse → search "BRAT") and enable it.
2. Open BRAT's settings and choose Add Beta Plugin.
3. Enter this repo: stephenkall/obsidian-confluence-vault-uploader, and confirm.
4. Enable Confluence Vault Uploader under Community plugins.

From then on, BRAT checks this repo's GitHub Releases for you and can update the plugin automatically — no manual re-download needed for future versions.

Option B: Manual install

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create the folder <your-vault>/.obsidian/plugins/confluence-vault-uploader/ — the folder name must match the id in manifest.json (confluence-vault-uploader)
3. Copy all three files into that folder
4. In Obsidian: Settings → Community plugins → reload, then enable Confluence Vault Uploader
5. Repeat these steps for each new release — this method does not auto-update.

To build from source:

git clone https://github.com/stephenkall/obsidian-confluence-vault-uploader.git
cd obsidian-confluence-vault-uploader
npm install
npm run build
# copy main.js + manifest.json + styles.css to your vault's plugin folder

Configuration

Open Settings → Confluence Vault Uploader and fill in:

After filling in the root page URL, a confirmation line shows the extracted space and page ID. Use Test Connection to verify credentials before syncing.

Usage

1. Open the command palette (Ctrl+P / Cmd+P)
2. Run Sync vault to Confluence
3. A progress notice appears for each file; a final notice reports success/failure counts

Commands

Sync visibility

You never have to guess whether a sync is running, idle, or stuck:

• The status bar (bottom of the Obsidian window) always shows the current state and updates per file during a sync. Click it to open the full status panel.
• The log level setting (Settings → Confluence Vault Uploader → Sync visibility) controls how much detail is captured: None (errors only), Normal (per-file progress), or Verbose (per-request detail). Errors are always captured regardless of this setting. Per Obsidian's plugin guidelines, the developer console only ever shows errors — everything else lives in the in-app log ("Show Confluence sync log").
• If a sync is interrupted by an unexpected error, it no longer fails silently — a notice explains what happened, progress up to that point is saved, and the failure is recorded in the log and in the status panel's "last sync" summary.

Concurrent syncing

Both sync phases can process multiple pages at once instead of strictly one at a time. Set Sync concurrency (Settings → Confluence Vault Uploader → Performance) to how many pages to sync simultaneously — 1 disables concurrency (original one-at-a-time behavior), higher values finish large vaults faster. A few things worth knowing:

• Folder creation is safe under concurrency: if multiple files need the same not-yet-created parent folder at once, they share a single in-flight creation instead of racing to create it twice.
• If Confluence responds with a rate limit (429), the sync automatically waits (honoring the server's Retry-After when given, or an exponential backoff otherwise) and retries — this is normal, self-correcting behavior at higher concurrency, not a failure.
• If you're unsure what to pick, the default (4) is a reasonable balance; drop it to 1 if you want the original strictly-sequential behavior (e.g. for easier log reading), or if you're hitting persistent rate-limit errors even after the automatic backoff.

Cleanup

A sync only ever adds or updates pages — it never deletes anything on its own, even across many runs. If earlier (buggier) versions of this plugin left orphaned pages behind under old titles, those stay until you explicitly remove them.

Find Confluence pages not in vault helps with exactly that: it walks every page under your configured Root page and compares it against what the vault currently produces, then shows a checklist of anything left over — before touching anything. A few safety rails are built in:

• It only ever compares against the subtree under your Root page URL — never the whole space — so the blast radius is scoped to what this plugin actually manages. It refuses to run if no root page is configured.
• It refuses to run until every file in the vault has been synced in the current session, so the comparison reflects the vault's actual current state rather than a partial one.
• Nothing is deleted until you review the list and confirm — every item is checked by default, but you can uncheck any you want to keep.
• Deleted pages go to Confluence's Trash (recoverable there for a retention period), not a permanent purge.

This only prunes the Confluence side. It never creates, modifies, or deletes anything in your vault.

Folder pages and MOC files

A file whose name starts with _ (e.g. _Overview MOC.md) is treated as the content of its parent folder's Confluence page rather than as a separate child page. This lets you write a rich index for each section.

01 - Overview/
├── _Overview MOC.md      ← becomes the body of the "01 - Overview" page
├── Architecture.md       ← child page
└── System Landscape.md   ← child page

Wiki links

All standard Obsidian link formats are supported and resolved to real Confluence URLs in Phase 2:

Callouts

Notes

• Pages are matched by title within their parent; renaming a file creates a new page (the old one is not deleted automatically)
• The sync is safe to re-run; existing pages are updated in place
• Images embedded via ![[file.jpg]] become links (Confluence image upload is not yet supported)
• Task list items (- [ ] / - [x]) are converted to ☐/☑ plain text, since Confluence storage format does not support HTML checkbox elements
• Confluence requires page titles to be unique within a space, regardless of folder structure — unlike a filesystem, which allows the same filename in different folders. If a file or folder name is used more than once in the vault (e.g. paired "logical"/"physical" exports sharing a GUID filename), that page's Confluence title is automatically prefixed with just enough of its parent path to make it unique (e.g. seg_0/GUID.xml instead of a bare GUID.xml), instead of failing with Request failed, status 400. This only affects the Confluence-visible title — internal link resolution always uses the full vault path, so links are unaffected. A page that already synced under its old bare title (e.g. from before this behavior existed) is not automatically renamed — on a vault with many collisions, attempting that in bulk on every sync risks its own update conflicts. It's purely cosmetic and does not affect sync correctness; run Reconcile Confluence page titles any time you want those brought in line with their sibling's scheme.

Privacy & permissions

This plugin reads every .md file in your vault to build the page hierarchy and resolve cross-file links. No file content is sent anywhere except to the Confluence instance you configure. Your Confluence credentials (URL, username, API token) are stored locally in Obsidian's plugin data and are never transmitted to any third party.