How to Import Markdown Files into Confluence

Confluence is where your team documents things. Markdown is where developers write things. The problem is they don't naturally talk to each other — pasting markdown into Confluence turns your beautiful formatting into a wall of symbols.

Markdown Importer for Confluence & Markdown Exporter bridges that gap. Here's exactly how to use it to get markdown into Confluence — whether that's a single file, a folder of docs, or an entire GitHub repository.

---

Option 1 — Import a Single Markdown File

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

1. Open any Confluence space and navigate to where you want the page
2. Click Apps → Markdown Importer
3. Click Import Files and upload your .md or .mdx file
4. Preview the rendered output
5. Select the parent page (or leave it at the space root)
6. Click Import

Your page is created with all formatting intact — headings, tables, code blocks, images, and lists all convert cleanly.

---

Option 2 — Import a Folder of Markdown Files

Best for: importing a docs folder from a project, a wiki from GitHub/GitLab, or any set of related documents that form a hierarchy.

1. Zip your markdown folder (preserving the folder structure)
2. Open Markdown Importer from the Apps menu
3. Click Import Files and upload the ZIP
4. The importer reads your folder structure and maps it to a Confluence page hierarchy
5. Preview the page tree — reorder or exclude pages as needed
6. Select the parent page in Confluence
7. Click Import

The folder hierarchy becomes your Confluence page tree:

docs/
├── getting-started/
│   ├── index.md        → Getting Started (parent)
│   ├── installation.md → Installation (child)
│   └── quick-start.md  → Quick Start (child)
└── features/
    ├── index.md        → Features (parent)
    └── api.md          → API Reference (child)

Internal links between files are automatically converted to Confluence page links — cross-references stay intact.

---

Option 3 — Import from a GitHub or GitLab Repository

Best for: syncing developer documentation directly from source control into Confluence — keeping your /docs folder and your Confluence space in sync.

1. Open Markdown Importer from the Apps menu
2. Click Import from URL
3. Paste your GitHub or GitLab repository URL (or a specific folder URL)
4. The importer fetches your markdown files directly from the repo
5. Preview the page tree
6. Select the destination in Confluence
7. Click Import

This is the fastest path from a Git repo to Confluence — no need to clone locally, zip files, or manually copy content.

---

Option 4 — Import via REST API (Automated Pipelines)

Best for: CI/CD pipelines, documentation-as-code workflows, and teams that want to automatically sync docs on every commit.

The Markdown Importer exposes a REST API that lets you trigger imports programmatically. Add it to your CI pipeline and your Confluence pages update automatically whenever your docs change.

See the REST API documentation for full details.

---

What Gets Preserved

The importer handles the full range of standard markdown formatting:

• Headings — H1–H6 map to Confluence heading levels
• Text formatting — bold, italic, strikethrough, inline code
• Tables — including alignment and header rows
• Code blocks — with language and syntax highlighting
• Lists — ordered, unordered, nested, and task lists with checkboxes
• Images — uploaded as Confluence attachments and linked inline
• Blockquotes — converted to Confluence info/note panels
• Links — external URLs preserved; internal .md links converted to Confluence page links
• Frontmatter — YAML frontmatter is parsed (title, date, author, tags can map to page properties)

---

Tips

Check your image paths. If your markdown references images with relative paths, make sure the images are included in your ZIP or accessible at the URL before importing.

Use frontmatter for page titles. If your files have title: in the YAML frontmatter, the importer uses that as the Confluence page title instead of the filename.

Import into a staging space first. For large imports, run it in a test space before hitting production. It's easy to re-import if anything looks off.

Bulk import is unlimited. There's no cap on how many pages you can import in one go — import an entire repository if you need to.

---

Getting Started

Install Markdown Importer for Confluence & Markdown Exporter from the Atlassian Marketplace — free to try.

Full documentation is at /docs/markdown-importer-for-confluence.

---

Questions? Reach out via our support portal.