Documentation

Markdown Tree Import for Confluence — setup, behaviour, supported syntax and troubleshooting.

01 Quick start

1. Zip your Markdown folder. Include the images, keeping them where your Markdown expects them.
2. In Confluence, open Apps → Markdown Import.
3. Choose the .zip, pick a target space, and optionally paste a parent page ID.
4. Click Show plan. Nothing is written yet — review the tree it proposes.
5. Click Import.

02 Folders to pages

Your folder tree is reproduced as a Confluence page tree.

• Each .md, .markdown or .mdx file becomes one page.
• A folder's README.md (or index.md) becomes that folder's own page, and the folder's other files become its children.
• A folder without one gets a generated page listing its children.
• If every file sits beneath a single top-level folder, that folder is trimmed so you don't get a pointless extra level.

docs/
├── README.md       →  Product Documentation      (top page)
├── install.md      →  Installation               (child)
├── api/
│   ├── README.md   →  API Reference              (child)
│   └── auth.md     →  Authentication             (child of API Reference)
└── guides/         →  Guides                     (generated folder page)
    └── intro.md    →  Getting Started            (child of Guides)

03 Page titles

Chosen in this order:

1. A title: field in YAML front matter.
2. The document's first heading. Headings inside fenced code blocks are correctly ignored — a shell example starting # npm install will not become your page title.
3. The file name, cleaned up: getting-started.md becomes "Getting started".

Confluence requires titles to be unique within a space. When two files would collide, the second gets its folder name appended — Notes (Beta) — and this is listed in the import report.

04 Images

Every referenced image is uploaded as a real Confluence attachment on the page that uses it, and the page points at that attachment. Nothing links back to your zip or to an external host.

05 Links

A relative link to another Markdown file is rewritten to the page that file became, keeping any anchor.

[Installation](docs/install.md)      →  the "Installation" page
[Setup](./install.md#requirements)  →  that page, anchor preserved
[Home](../README.md)                →  the parent page
[Atlassian](https://atlassian.com)  →  left untouched

A relative link pointing at a file that was not part of the import stays as plain text rather than becoming a broken link.

06 Supported Markdown

Raw HTML inside Markdown is not executed. Where it appears it is preserved as a code block and noted in the report, so nothing is silently lost.

07 Re-importing

Running the same import again updates the pages it created rather than duplicating them — matched by page title within the target space. Fix a typo in your repository, import again, and only the changed pages differ.

08 The import report

Every run ends with a report listing:

• pages created, and pages that failed with the reason for each
• images that could not be uploaded, with the error
• images a page referenced but the zip did not contain — showing the exact path looked for
• images in the zip that nothing references
• titles renamed to stay unique

A bad file never stops the run. Everything else still imports, and the report tells you precisely what to fix.

09 Limits

• Speed is bounded by the Confluence API, not by your machine: expect roughly 25–40 pages per minute. A 70-page repository takes about two minutes; a 500-page one takes fifteen. Plan a large first import accordingly.
• The zip is opened in your browser, so archive size is bounded by your own machine rather than by a server. Repositories of a few hundred pages import comfortably.
• Keep the tab open while importing; closing it stops the run. Pages already created remain, and running again continues safely.
• Page permissions are not derived from your repository — imported pages inherit the space's permissions.
• Importing never deletes. Removing a file from your repository does not remove the page it previously created.

10 Troubleshooting

The space list is empty

You need permission to create pages in at least one space. Ask your Confluence administrator, then reload the page.

"Image not found in zip"

The report shows the exact path that was looked for. Usually the image sits outside the folder you zipped — re-zip from a level high enough to include both the Markdown and the images.

Some pages have the wrong title

Titles come from front matter, then the first heading, then the file name. Add a # Heading at the top of the file, or a title: in front matter, and import again.

A page failed with a permissions error

You lack create or edit rights in that space, or the page is restricted. The rest of the import still completed — fix the permission and run it again; only the missing pages are created.

Anything else

Email support@kunfeyekun.co.uk with the import report and, if you can, the file that caused it. Replies within 4 business hours, Monday to Friday.