# How to Import Markdown Files into Confluence (Step-by-Step Guide)

# 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](https://marketplace.atlassian.com/apps/1231894/markdown-importer-for-confluence-markdown-exporter?hosting=cloud&tab=overview) 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](/docs/markdown-importer-for-confluence/rest-api) 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](https://marketplace.atlassian.com/apps/1231894/markdown-importer-for-confluence-markdown-exporter?hosting=cloud&tab=overview) from the Atlassian Marketplace — free to try.

Full documentation is at [/docs/markdown-importer-for-confluence](/docs/markdown-importer-for-confluence).

---

_Questions? Reach out via our [support portal](https://yamuno.atlassian.net/servicedesk/customer/portals)._