Importing Markdown

What the app expects inside the archive, what becomes a page, and what happens when you run it twice.

What it does. Turns a folder of Markdown into real Confluence pages, keeping the folder structure as the page tree, uploading the images the pages refer to, and rewriting the links between them so they point at the pages rather than at files.

Where it is. The Import tab on the Markdown Toolkit page in the space sidebar. Drop a .zip, or one or more .md files, onto the drop zone.

Confluence space → Markdown Toolkit → ImportIllustration

ExportImport

Drag and drop files here, or click to browse

Supported: .md, .zip

Files to import: 5 · 2 attachments

📄 Guide

📄 Install+ 1

📄 Configure

📄 Troubleshooting+ 1

📄 Reference

Import everything under a page called

Engineering Handbook (imported)

Created first, in your name — which is also the permission check.

When a page with that title already exists

Leave the existing page alone

Upload images and files the pages refer to

Take the page title from the first heading

Import (5)

Import complete. 4 created, 1 skipped, 2 attachments.

One page was left alone because a page with that title already existed.

How the archive should look

There is one rule, and everything else follows from it: a folder becomes a page when a Markdown file sits next to it with the same name.

An archive the app reads as a three-level tree

01-Guide.md              ← becomes the page "Guide"
01-Guide/                ← its children live here
  01-Install.md          ← becomes "Install", under Guide
  01-Install/
    attachments/
      screen.png         ← uploaded onto the Install page
  02-Configure.md
02-Reference.md

01-Guide.md and 01-Guide/ are the same page: the file is its content, the folder holds its children. This is exactly the shape an export from this app produces, so an export imports back without losing the tree.

A folder with no matching file still works

If guide/ has no guide.md beside it, the app creates an empty page called Guide so the nesting is not lost and the children do not land at the top of the space. It is a placeholder, not a guess at content.

A flat folder is fine too. Ten .md files with no subfolders become ten pages side by side. Nesting is optional; the app only reproduces the structure you give it.

Where the page title comes from

In this order, first match wins:

1The title in YAML front matter, if the file has a front-matter block. This is the only source that survives a title a filename could not hold — a page called Q3: goals / draft exports as Q3-goals-draft.md, and only the front matter still knows what it was called.
2The first heading in the document — # Getting started. When the title comes from here, the heading is removed from the body, because Confluence renders the page title above the content already and leaving it in reads as a stutter.
3The filename, with its 01- ordering prefix stripped and hyphens turned back into spaces.

The front-matter block itself never appears on the page — it is metadata, and importing it as literal --- title: … --- text would visibly damage the content.

Images and other files

Anything in the archive that is not Markdown is a candidate attachment, and the app uploads it onto the page whose Markdown refers to it, then rewrites the link so Confluence renders the image.

Referenced, not everything. A file nothing points at is left out. A docs repository carries stylesheets, fonts and build output that have no business becoming Confluence attachments.

Resolved from the file that links to it, not matched by name — because two pages can each have an attachments/diagram.png, and matching on the filename would attach one page's picture to the other.

If an upload fails, the page still arrives

The page is created and the failure is counted, because a page is worth having even without its diagram. The result says how many attachments could not be uploaded — which is the number that decides whether the import can be called complete.

Links between the files

A link to another .md in the archive becomes a Confluence link to the page that file became — resolved against the archive, so [the installer](./guide/install.md) points at Install, not at a page named after the link text. Links to anything outside the archive are left as they are.

The settings

Import everything under a page called…: The name of the page the whole archive is created beneath. It is created first, in your name — and that is also the permission check: if you cannot create pages in this space, the import stops there and nothing else is written.
When a page with that title already exists: Confluence requires page titles to be unique within a space, so a second run of the same import has to be told what to do. Leave the existing page alone (the default) keeps it and counts it as skipped, and its children still go underneath it. Replace the existing page overwrites the body. Create a second page adds a suffix — Guide (2).
Upload images and files the pages refer to: On by default. Turn it off to bring in the text only.
Take the page title from the first heading: On by default. Turn it off if your filenames are the titles you want and your headings are not.

Running the same import twice is safe

With the default conflict setting, the second run creates nothing and reports how many pages it left alone. The destructive choice is one you have to pick on purpose — not one you get by pressing the button again.

What it reports

When the job finishes: how many pages were created, replaced and left alone, how many attachments arrived, and how many pages or attachments failed — with the file path of each failure, so you can fix that one file rather than re-run the lot.

One bad file does not stop the job. A file that fails to convert or to create is counted and the import carries on, so a single malformed document does not cost you the other four hundred.

A note on what comes back

Markdown and Confluence are not the same language, and a round trip is a conversion in each direction. Headings, lists, tables, code blocks, task lists, links, images and GitHub-style alerts survive both ways. A Confluence macro that had no Markdown equivalent on the way out does not come back on the way in — the export left a comment where it was, and that comment is what returns.