Migrating from Confluence to a self-hosted markdown wiki

Confluence is a capable product. It's also one of the most common things engineering and ops teams quietly decide to leave. If you've landed here, you've probably already had the internal conversation — the question now is whether the move is worth it, and what it actually takes. This post is a practical walkthrough, not a takedown. Atlassian shops stay on Confluence for good reasons, and we'll be honest about those too.

Why teams actually leave Confluence

The reasons are rarely dramatic. They accumulate.

Cost at scale. Per-seat pricing is fine for twenty people and starts to sting at two hundred. When every contractor, every read-mostly stakeholder, and every "I just need to check one page" account is a billable seat, the bill grows faster than the value for a lot of orgs.

Heaviness. Confluence is a big application. Pages can be slow to open and slow to edit, the editor sits between you and your content, and simple things — paste some text, fix a typo, restructure a page — can feel like more ceremony than they should. Teams that live in their docs feel this friction every day.

Lock-in. Content lives in Confluence's storage format and its macro ecosystem. That's fine until you want it somewhere else. The richer your pages (macros, embedded panels, page properties), the harder they are to take with you cleanly.

Editing speed. Writers comfortable in markdown — most engineers — find the rich-text-first model slower than typing plain text and letting it render.

None of this means Confluence is bad. It means the fit degrades for a specific kind of team: technical, markdown-comfortable, cost-conscious, and wanting their knowledge in a format they own.

What you actually have to plan for

A wiki migration is a content migration, and content migrations fail on the boring details. Plan these before you move a single page.

Export. Confluence can export a space to HTML, PDF, or XML, and the REST API can pull page content and metadata. You'll convert from Confluence's storage format (XHTML-ish, macro-laden) into markdown. Tools exist for this, but treat the output as a first draft, not a finished import.

Content fidelity. This is where time goes. Standard formatting — headings, lists, tables, code blocks, links — converts well. Confluence macros are the hard part: panels, info/note boxes, expand sections, status labels, page-properties reports, embedded Jira issues, and the long tail of marketplace macros. Decide per macro: map it to a native equivalent, flatten it to plain content, or drop it. Inventory your most-used macros first; you'll usually find a handful account for most pages.

Attachments. Images, diagrams, and files are referenced, not inline. Your export has to pull the binaries and rewrite every reference to point at the new location. Broken image links are the most common post-migration complaint — budget for verifying them.

Permissions mapping. Confluence space and page restrictions rarely map one-to-one onto a new tool's model. Write down your current access model — who can see what, who can edit what — and translate it into the target's spaces/roles before import, rather than discovering gaps afterward.

Redirects. People have Confluence URLs in bookmarks, Slack messages, tickets, and other docs. If you can keep the old instance read-only for a while and/or maintain a URL map from old page to new, you avoid the "all our links are dead" moment. Even a simple lookup table from Confluence page ID to new URL saves a lot of pain.

A sane rollout: migrate one space as a pilot, check fidelity and links honestly, fix your conversion process, then do the rest. Keep Confluence read-only during the transition instead of cutting over cold.

What a markdown-native target buys you

Moving to a markdown-native wiki isn't just a cheaper Confluence. The format itself changes what you can do.

Portability. When your canonical content is markdown, export stops being a feature you hope works and becomes the natural state of the data. There's no proprietary storage format between you and your words. Leaving — even leaving the tool you just migrated to — is a git clone or a file copy, not a project.

grep and diff. Plain text is the most durable, most tooled format in computing. You can grep across your whole knowledge base, diff a page's history line by line, review doc changes in a pull request, and script bulk edits. Your docs behave like code because they're text like code.

Agent-readability. This is the newer, underrated one. LLM agents read and write markdown natively. A markdown wiki is something an agent can ingest, search, and update without a translation layer — which matters more every quarter as teams wire assistants into their documentation. (To be clear, this isn't unique to markdown tools — Atlassian ships Rovo and an MCP server for Confluence too. The difference is that with a markdown-native store, the agent and the canonical format are already the same thing.)

The honest tradeoffs

Switching costs you things. Be clear-eyed about them, because for some teams they're decisive.

Enterprise breadth. Confluence has a deep marketplace, mature templates, page analytics, and years of polish. A leaner tool won't match all of it on day one.

Deep Jira workflow. If your team lives inside Atlassian — Jira automations triggering Confluence updates, tight issue-to-doc linking, Confluence as the system of record wired into Atlassian governance — that integration is genuinely hard to replicate, and it's the single best reason to stay.

Governance and compliance. Enterprise audit logging, fine-grained permissions, retention policies, and the certifications procurement asks for are areas where established platforms have a real head start. If compliance owns your tooling decision, weigh this heavily.

If those three describe you, staying on Confluence is a defensible call. Migration pays off most for teams whose needs are simpler than the platform they're paying for.

tela as one destination

tela is one place migrated content can land, built around the ideas above. Its entire product — markdown-native wiki, live collaboration, search, organizations and roles, and a built-in MCP server (39 tools) — is open source under AGPL-3.0; the repo is github.com/zcag/tela. A separate Enterprise add-on (SSO, audit, SCIM) is source-available and key-gated for enterprise admins. You can self-host the whole core via docker compose, or start on the free cloud tier at telawiki.com.

A few things that fit the migration story specifically:

• Canonical markdown, no block table. A page's body is markdown, permanently. Export and portability are the default, not a bolt-on.
• Built-in MCP server. Agents are first-class — they read and write your wiki through the same tools your UI uses.
• Search that scales. Postgres full-text search plus optional semantic search over your content.
• Atlas auto-generates a cited wiki from your git history and Jira. Note the direction: tela documents from Jira — it reads Jira to write docs, it doesn't drive your Jira workflow. So if deep two-way Jira automation is what keeps you on Confluence, that gap stays.

tela isn't the only good destination — Outline is another well-regarded option (BSL-1.1 licensed), and the right answer depends on your team. The honest summary: if you're a technical, markdown-comfortable team feeling cost and weight, a self-hosted markdown wiki is very likely an upgrade. If you're an Atlassian-deep shop running on Jira-driven workflows and enterprise governance, Confluence is doing real work for you, and "it's expensive" alone isn't a reason to move. Migrate because the format and the fit are better — not just because the bill is smaller.