How to Import Markdown into Confluence

Short answer: Confluence Cloud doesn't import .md files on its own. With Markdown Importer for Confluence, open a page's ••• menu, choose Markdown Importer & Exporter, upload a .md file or a ZIP of a docs folder, preview it and click Import. Headings, tables, code blocks and images become native Confluence content, and folders become a page tree.

Confluence is where your team documents things. Markdown is where developers write things. The two don't naturally talk to each other: paste Markdown into a Confluence page and your formatting turns into a wall of symbols.

This guide shows how to import Markdown into Confluence with Markdown Importer for Confluence, whether that's a single file, a folder of docs, or a repository you want to keep in sync.

---

Option 1: Import a Single Markdown File

Best for: a README, a runbook, an architecture decision record, or any standalone document.

1. Open the Confluence page you want the new page to sit under
2. Click the ••• (More actions) menu and select Markdown Importer & Exporter
3. Choose your .md file
4. Use Preview to check how the content will look in Confluence
5. Click Import

You can also open the app from the global Apps menu instead of a page. From there you pick the target space (or several spaces) yourself.

Headings, tables, code blocks, lists and images are converted to native Confluence content.

---

Option 2: Import a Folder of Markdown Files

Best for: a project's docs folder, an exported wiki, or any set of related documents that form a hierarchy.

1. Zip your Markdown folder, keeping the folder structure and any local images inside it
2. Open Markdown Importer & Exporter from a page's ••• menu or from the Apps menu
3. Upload the .zip (or select several .md files at once)
4. Preview the files and review any conflicts the importer flags, such as pages that already exist
5. Click Import

Your folder structure becomes the Confluence page tree. Each folder becomes a parent page, and the files inside it become child pages:

docs/
├── getting-started/        → parent page
│   ├── installation.md     → child page
│   └── quick-start.md      → child page
└── features/               → parent page
    └── api.md              → child page

Confluence requires page titles to be unique within a space, so rename duplicates (two overview.md files in different folders, for example) before importing. For large folders, the bulk import guide covers preparation and checks in more detail.

---

Option 3: Import Docs from a GitHub or GitLab Repository

The importer works with files, not repository URLs, so there are two ways to bring repo docs across:

• One-off migration. Clone the repo (or download the docs folder), zip the docs/ directory, and upload it as in Option 2. The GitHub and GitLab migration guide walks through this step by step.
• Ongoing sync. Call the importer's REST API from your CI pipeline so changed files are pushed to Confluence on every merge. The GitHub to Confluence sync guide has a working GitHub Actions workflow and script.

---

Option 4: Import via the REST API

Best for: CI/CD pipelines, docs-as-code workflows, and scripts.

The REST API accepts one page per request as JSON (space, parent page, title and the Markdown content) and can create a new page or update an existing one. It handles page content only, so attachments need a separate step. See the REST API documentation for setup and examples.

---

What Gets Converted

The importer handles standard Markdown formatting:

• Headings: H1 to H6
• Text formatting: bold, italic, strikethrough, inline code
• Tables: converted to Confluence tables
• Code blocks: with syntax highlighting
• Lists: ordered, unordered, nested, and task lists as Confluence checkboxes
• Images and attachments: local files are uploaded as Confluence attachments and the references are updated; remote images work too
• Front matter: the import options include importing YAML front matter as page properties

A few things to check after an import, based on the app's known issues:

• Links between files. Relative links such as [Setup](../setup.md) may not always resolve to the right Confluence page. Spot-check them and fix any that point to the wrong place.
• Extensions. Footnotes, custom containers and other non-standard syntax may not render as expected.
• Complex tables. Merged cells and advanced formatting may need tidying.

---

Tips

Check your image paths. If your Markdown references images with relative paths, include those images in the ZIP so they can be uploaded with the pages.

Import into a test space first. For large imports, try a small subset in a sandbox space before importing into production.

Bulk import has no fixed limit. You can import as many files as you need in one go. Very large batches take longer because of Confluence API rate limits.

Keep files under 2 MB. Very large single Markdown files may fail or be slow. Split them into smaller pages.

---

Getting Started

Install Markdown Importer for Confluence from the Atlassian Marketplace. It's free to try.

Full documentation is at /docs/markdown-importer-for-confluence, including a quick start guide.

---

Questions? Reach out via our support portal.