Convert Confluence HTML to Markdown

Confluence is a common source of documentation that teams want to migrate or archive. When you export a Confluence page, you get HTML — which is not directly useful in Obsidian, Notion, GitHub, or any Markdown-based system. Converting that HTML to Markdown is the bridge between the two worlds.

How to Export a Confluence Page as HTML

Confluence supports several export formats. For the HTML-to-Markdown workflow, you want the HTML export:

Single page export (Confluence Cloud):
Open the page → Click the three-dot menu (More actions) → Export → Export to HTML. Confluence downloads a .html file.

Single page source (any version):
Open the Confluence page in your browser → Right-click anywhere on the page content area → View Page Source (or Ctrl+U / Cmd+Option+U). Select all and copy the full page HTML.

Space export (Confluence Cloud admin):
Space Settings → Export Space → HTML. Downloads a zip of .html files for the entire space. Useful for bulk migration.

For the converter, the single page approach gives the cleanest result — either the exported .html file content or the Inspect-based content element copy.

Getting Clean Content HTML from Confluence

Confluence page HTML includes a lot of navigation, sidebar, and header content alongside the actual page content. For the cleanest Markdown output, copy only the main content area:

1. Open the Confluence page
2. Right-click on the main content area (the article body, not the sidebar)
3. Select Inspect (or Inspect Element)
4. In the Elements panel, look for a container element like <div class="wiki-content"> or <div id="main-content"> — the exact class varies by Confluence version and theme
5. Right-click that element → Copy → Copy outerHTML

This gives you just the page content without navigation, breadcrumbs, page actions, and sidebar widgets that would clutter the Markdown output.

Sell Custom Apparel — We Handle Printing & Free Shipping

What Confluence Content Converts Well

Converts cleanly:

• Headings (H1-H4) — Confluence page structure maps directly to Markdown heading levels
• Bold and italic text
• Bulleted and numbered lists (including nested)
• Code blocks — Confluence code macros output as <pre><code> which converts to fenced Markdown code blocks
• Tables — standard Confluence tables convert to GFM pipe syntax
• Links — internal and external links with text preserved
• Blockquotes / callout content (partially)

Needs manual cleanup:

• Confluence macros (info panels, warning boxes, expand sections, page includes) — these are rendered as styled divs that may produce fragmented Markdown
• Attached images — image tags will have Confluence-internal src URLs that will break after migration
• Page tree / child page lists — these are dynamic macros with no Markdown equivalent
• Confluence-specific formatting like colors, highlights, and text sizing — these are CSS-based and stripped during conversion

Post-Conversion Cleanup for Confluence Migration

After converting, a consistent set of cleanup tasks applies to most Confluence migrations:

1. Fix image references — Confluence image src URLs point to the Confluence server. Download the images, store them in your new system, and update the Markdown image paths.
2. Replace macro outputs — Info panels, warning boxes, and expand sections render as plain divs. Manually convert important ones to Markdown callout syntax (Obsidian), Notion callout blocks, or GitHub note/warning syntax.
3. Update internal links — Links to other Confluence pages point to Confluence URLs. Update them to reference the correct Markdown file paths in your new system.
4. Check heading levels — Confluence sometimes uses H1 for section titles within a page. Verify the heading hierarchy makes sense in your new context.
5. Add frontmatter — For systems like Obsidian or Jekyll, add YAML frontmatter at the top with metadata (title, date, original URL, author).

Frequently Asked Questions

How do I convert Confluence pages to Markdown?

Export the page as HTML from Confluence (three-dot menu → Export → HTML). Open the file, copy the content HTML, paste into the converter, and download the .md output.

Does Confluence have a built-in Markdown export?

Confluence Cloud does not natively export Markdown. Third-party apps in the Atlassian Marketplace add this, or use the HTML export and convert it with the free browser tool.

Will Confluence code blocks convert to Markdown code blocks?

Yes. Confluence code macros render as <pre><code> elements which convert to fenced Markdown code blocks. The language tag is preserved if Confluence specified it.

What about Confluence images after converting to Markdown?

Image tags convert to Markdown image syntax but the src URLs point to your Confluence server. You need to download the images and update the paths in the Markdown for them to work outside Confluence.