How to Bulk Import Markdown Files into Confluence

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.

---

What "Bulk Import" Means in Practice

A bulk import takes a ZIP archive 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 will become a parent page in Confluence. The nesting can be as deep as you need.

File naming: The importer uses the markdown filename (without the .md extension) as the Confluence page title. Hyphens are replaced with spaces and the first letter is capitalized — getting-started.md becomes "Getting Started." If a file has a title field in its frontmatter, that takes precedence over the filename.

---

Step 2 — Add Frontmatter (Optional but Recommended)

YAML frontmatter at the top of each markdown file gives the importer more information to work with:

---
title: "Advanced Configuration Options"
---

# Advanced Configuration Options

Rest of the content...

If a title is present, the importer uses it as the Confluence page title. This lets you have descriptive filenames in the repo while setting human-readable titles in Confluence.

Other frontmatter fields are not processed by the importer but are preserved if you later export back to markdown.

---

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

Image references in the markdown should be relative paths:

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

The importer uploads the images as Confluence attachments and updates the references in the page content to point to the uploaded attachments. The relative path structure is resolved relative to the markdown file's location in the ZIP.

---

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

The ZIP should contain the root folder (docs/), not just the contents. This preserves the top-level folder name, which becomes the title of the root-level parent page if you're importing the whole tree.

If you'd rather the import start with the contents of the folder (not the folder itself as a parent page), zip the contents directly:

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

---

Step 5 — Import the ZIP

1. Navigate to the Confluence page that should be the parent of the imported content
2. Click ••• (More actions) → Markdown Importer & Exporter
3. Click Upload and select your ZIP archive
4. Configure the import options:
   • Page Hierarchy — enable this to create parent/child pages from the folder structure
   • Overwrite existing pages — enable if you're re-importing and want to update pages that already exist
5. Click Import

A progress indicator shows pages being processed. For large imports (100+ pages), this may take a few minutes. The importer processes pages in small batches to avoid hitting Confluence API rate limits.

---

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

If you're importing into multiple Confluence spaces in one operation, use the global access point instead of the page-level entry:

1. Click Apps in the Confluence global navigation
2. Select Markdown Importer & Exporter
3. Choose the target space and parent page from the dropdowns
4. Upload your ZIP and configure options
5. Import

Admins can use this to import documentation across multiple spaces without navigating to each target page individually.

---

Handling Large Imports

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 any issues before continuing.

After the first batch, check a few imported pages to verify:

• Page titles are correct
• Images are displaying (not showing broken links)
• The hierarchy is correct in the page tree
• Formatting (code blocks, tables, headings) rendered properly

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

---

Common Issues

Broken image references: Usually caused by images being outside the ZIP or using absolute paths instead of relative paths. Fix the markdown to use relative paths and ensure images are inside the ZIP.

Wrong page titles: The filename is being used instead of frontmatter. Add title: frontmatter to the affected files.

Hierarchy not matching the folder structure: Page Hierarchy option was not enabled during import. Re-import with the option enabled — use "Overwrite" to update the existing pages.

Import stops partway through: Likely a rate limit from the Confluence API. Wait a few minutes and re-import the remaining files. Use "Overwrite" so already-imported pages are updated rather than duplicated.

---

Install Markdown Importer for Confluence →

Read the documentation →