Sarah Chen, SEO Content Strategist
What Is Confluence to Markdown Conversion
Confluence to Markdown conversion transforms wiki pages authored in Atlassian Confluence into GitHub-Flavored Markdown — the open, portable plain-text format used across developer tools, documentation platforms, and version control systems. Confluence stores content in a proprietary XML-based format (Confluence Storage Format) with custom macro tags. Converting this content to Markdown makes it accessible outside the Atlassian ecosystem.
Teams convert Confluence content to Markdown when migrating to a Git-based documentation workflow, when moving to a modern documentation platform like Docusaurus, GitBook, or Mintlify, or when consolidating multiple documentation sources into a single Markdown repository. This tool handles the conversion client-side in your browser — no Atlassian API credentials or server-side processing required.
How to Export Confluence Content
Page-level HTML Export
In Confluence Cloud: open the page → click ···(More actions) → Export → Export to HTML. The exported HTML file contains the fully rendered page content with macros expanded. In Confluence Server/Data Center: Tools → Export to Word or HTML (varies by version). Some Server instances allow viewing the page source by appending ?view=source to the page URL.
Space Export
To export an entire Confluence Space: Space Settings → Export Space → HTML format. This creates a ZIP archive with individual HTML files for each page in the space, maintaining the page hierarchy as a folder structure.
Direct Copy-Paste
Select all content on the Confluence page (Cmd+A / Ctrl+A), copy, and paste into SmartMarkdown. Confluence populates the clipboard with HTML including the rendered macro output, which SmartMarkdown converts accurately.
Confluence Macro to Markdown Mapping
Confluence macros are Confluence-specific content blocks with no direct Markdown equivalent. SmartMarkdown maps them to the closest standard Markdown output:
- Code macro → fenced code block with language identifier (
```language) - Info panel →
> **ℹ️ Info:** content - Note panel →
> **📝 Note:** content - Warning panel →
> **⚠️ Warning:** content - Tip panel →
> **💡 Tip:** content - Expand macro → content exported as regular text (no collapse)
- TOC macro → replaced with generated heading list
- Status macro → inline bold text with status label
- Table → GFM pipe table
- Numbered headings → standard Markdown headings without numbers
Benefits
Escape vendor lock-in:Content in Markdown is not tied to Atlassian's platform, pricing, or continued availability. It works with every editor, version control system, and documentation platform.
Version control:Markdown files in a Git repository give your documentation the same change history, diff visibility, and review workflow as your code. Confluence's page history is useful but limited compared to Git.
Modern documentation stacks: Platforms like Docusaurus, Mintlify, and GitBook are Markdown-native and provide better developer experience, search, and customization than Confluence — but they require Markdown as input.
Common Use Cases
Engineering team documentation migration: Many engineering teams start on Confluence and later move their technical documentation to a Git-based system where docs live alongside code. SmartMarkdown converts each Confluence page in seconds, accelerating the migration.
Docusaurus/GitBook setup: Teams standing up a new Docusaurus or GitBook documentation site use this tool to seed it with existing Confluence content, rather than starting from a blank slate.
Atlassian license reduction: Companies moving away from Confluence use bulk Space export + SmartMarkdown to archive all documentation in portable Markdown before cancelling the subscription.
Tips for Accurate Conversion
- Prefer HTML export over copy-paste: For pages with many macros, the HTML export produces more complete and accurate output than clipboard paste.
- Expand all Expand macros before exporting: Some Confluence versions collapse Expand macros in the export. Expand them manually before exporting to ensure the content is included.
- Handle images separately: Confluence-hosted images use internal URLs. After conversion, download the images and re-host them, then update the image URLs in the Markdown editor.
- Check table headers: Confluence tables sometimes have all cells as
<td>instead of using<th>for the header row. Verify the first row is correctly formatted as a header in the converted output. - Clean up Jira macros: Jira Issue List and Jira macro output includes dynamic issue counts and statuses that won't be accurate in static Markdown. Replace these with static descriptions or links after conversion.