How to Bulk Import Markdown Files into Confluence

Short answer: Put the Markdown files in the folder structure you want, zip the folder together with any local images, and upload the ZIP to Markdown Importer for Confluence. Each folder becomes a parent page and each .md file a page under it, with images uploaded as attachments. Rename duplicate file names first, because Confluence page titles must be unique within a space.

If you're migrating documentation from GitHub, GitLab, Notion, or a static site generator, you're probably looking at more than a handful of markdown files. Importing them one at a time into Confluence isn't viable at scale. This guide covers how to bulk import dozens or hundreds of files at once, with the page hierarchy, images and formatting preserved. If you only have one or two files, the general Markdown import guide is quicker.

---

What "Bulk Import" Means in Practice

A bulk import takes a ZIP archive (or a multi-file selection) containing Markdown files and a folder structure, and creates a matching set of Confluence pages with the same hierarchy. A folder in the ZIP becomes a parent page in Confluence. A markdown file becomes a Confluence page. Images referenced in the markdown are uploaded as attachments and linked correctly in the page content.

The result: a ZIP with 80 files becomes 80 Confluence pages in the right hierarchy without anyone touching each one individually.

---

Step 1: Prepare Your Markdown Files

Install Markdown Importer for Confluence from the Atlassian Marketplace.

Before creating the ZIP, organize your Markdown files in the folder structure you want reflected in Confluence:

docs/
├── getting-started.md
├── installation.md
├── configuration/
│   ├── basic-setup.md
│   ├── advanced-options.md
│   └── environment-variables.md
├── how-to/
│   ├── first-steps.md
│   └── common-tasks.md
└── reference/
    ├── api.md
    └── cli.md

Each folder becomes a parent page in Confluence, with child pages mirroring its contents. Keep the nesting to a reasonable depth: very deep folder trees and unusual characters in file names can produce unexpected titles or hierarchy.

Unique names. Confluence requires page titles to be unique within a space, and that applies to folders that become parent pages too. Two files called overview.md in different folders will clash, so rename duplicates before you import. Stick to plain ASCII characters in file and folder names where you can.

---

Step 2: Decide What to Do with Front Matter

Many docs tools (Docusaurus, MkDocs, Hugo, Jekyll) put YAML front matter at the top of each file:

---
title: "Advanced Configuration Options"
tags: [config]
---

# Advanced Configuration Options

Rest of the content...

The importer's options include importing front matter as page properties, so you don't need to strip it out first. Run a small test import to see how your particular fields come through, and decide from there whether to keep them.

---

Step 3: Include Images in the ZIP

If your Markdown files reference local images, include them in the ZIP alongside the Markdown files:

docs/
├── getting-started.md          # references ./images/screenshot.png
├── images/
│   └── screenshot.png
└── reference/
    ├── api.md                  # references ../images/api-flow.png
    └── cli.md

Use relative paths consistently in the Markdown:

![Screenshot](./images/screenshot.png)

The importer uploads local images and other referenced files as Confluence attachments, keeps their original file names, and updates the references in the page content. Remote images (full URLs) work too. Confluence's attachment size limit still applies, typically 100 MB per file.

---

Step 4: Create the ZIP Archive

On macOS or Linux:

cd /path/to/your
zip -r docs-import.zip docs/

On Windows (PowerShell):

Compress-Archive -Path .\docs\ -DestinationPath .\docs-import.zip

Zipping the docs/ folder itself keeps it as a folder in the archive, so it can become a top-level parent page. If you'd rather start with the folder's contents, zip those directly:

cd /path/to/your/docs
zip -r ../docs-import.zip .

Either way, check the preview in the next step to confirm the tree looks the way you want.

---

Step 5: Import the ZIP

1. Navigate to the Confluence page that should be the parent of the imported content
2. Click ••• (More actions) and select Markdown Importer & Exporter
3. Upload your ZIP archive (or select multiple .md files)
4. Review the import options, such as keeping the folder structure as page hierarchy and how front matter and media are handled
5. Preview the content and check the conflicts the importer flags, for example pages that already exist with the same title
6. Click Import

Large batches take longer because the import works within Confluence API rate limits. When it finishes, the import stats show what was created.

---

Step 6: Import from the Global Apps Menu (Multiple Spaces)

To import into a space without starting from a page, or into several spaces at once, use the global access point:

1. Click Apps in the Confluence global navigation
2. Select Markdown Importer & Exporter
3. Choose the target space or spaces, and a destination page or folder
4. Upload your ZIP and review the options
5. Import

Admins can also import into all spaces in one operation from here.

---

Handling Large Imports

There's no fixed limit on the number of files, but for very large imports (500+ pages) consider splitting the ZIP by section and importing in batches. This makes it easier to review the output after each batch and fix issues before continuing. Individual Markdown files over about 2 MB may fail or be slow, so split very long documents into several pages.

After the first batch, check a few imported pages:

• Page titles are correct
• Images display (no broken references)
• The hierarchy matches the folder structure
• Formatting (code blocks, tables, headings) rendered properly
• Links between pages point to the right place

If something is off, it's usually a consistent issue (like image paths) that you can fix across the remaining files before the next batch.

---

Common Issues

Broken image references: Usually caused by images outside the ZIP or absolute local paths. Use relative paths and make sure the images are inside the ZIP. Occasional upload failures from network or API limits can be fixed by retrying the import or uploading the image by hand.

Title clashes: The importer reports conflicts when a page with the same title already exists in the space. Rename the file or folder, or choose a different destination.

Hierarchy not matching the folder structure: Check that the page hierarchy option was on and that the folders were inside the ZIP. Deeply nested folders and unusual characters in names can also cause surprises.

Links between pages not resolving: Relative links between Markdown files may not always resolve to the right Confluence page. Spot-check them after import and update any that are wrong.

Import stops partway through: Very large batches can run into Confluence API rate limits. Wait a few minutes, then import the remaining files in a smaller batch.

---

Keeping Imports Up to Date

A ZIP import is a one-off copy. If the source files keep changing in a Git repository, the importer's REST API can update pages from your CI pipeline instead. See how to sync GitHub docs to Confluence automatically for a working setup.

---

Get Markdown Importer for Confluence on the Atlassian Marketplace

Read the import documentation