Definitive PagesTeams write documentation in Markdown: in Git repos and wikis, in Obsidian, and more and more with AI tools. People read documentation in Confluence. Here are the four ways to put the two together, starting with the ones that cost nothing.
1. Paste it into the editor
Confluence Cloud turns Markdown shortcuts into formatting as you type, and Markdown you paste is often converted too.
- Good: free, and built in.
- Limits: one page at a time. Images, links between files and the folder structure don't come along, and nothing changes when the file does.
2. Show the file in a macro
Marketplace apps can render a Markdown file, often straight from Git, inside a macro on a page.
- Good: the page shows the latest version of the file.
- Limits: the text lives in the macro, not in the page, so Confluence search and page tools usually can't see it. Each file needs its own page and macro, and readers depend on the app and its connection to Git.
3. Publish from CI with an open-source tool
Command-line tools such as mark and md2conf push Markdown to Confluence from a build pipeline.
- Good: free, and automatic on every commit.
- Limits: someone has to set up and maintain the pipeline, API tokens and page IDs. Edits made in Confluence are usually overwritten on the next run.
4. Import the files as Confluence pages
An importer app like Definitive Pages turns a folder or .zip of Markdown into a page tree under any page you choose.
- Good: real, searchable pages, with the folder tree, links, images and code intact. Run it again on the same folder and it updates only what changed, leaving pages edited in Confluence alone. Git wikis, MkDocs, Docusaurus, Obsidian and Notion exports are understood.
- Limits: updates aren't automatic: you run the import again when the files change.
Confluence's own importers handle HTML and Notion exports but not Markdown, and they always create a new space.
At a glance
| Real, searchable pages | Keeps folders, links and images | Updates when files change | Setup | |
|---|---|---|---|---|
| Paste | Yes | No | No | None |
| Macro | No, the text stays in the macro | One file per macro | Yes, live | An app, often a Git connection |
| CI tool | Yes | Mostly | Yes, on each commit | Scripts and API tokens |
| Definitive Pages | Yes | Yes | Yes, when you re-import | None |
Which should you pick?
- For a page or two, paste.
- If a page must always show the latest file and search doesn't matter, use a macro.
- If an engineering team will own a pipeline, publish from CI.
- If a whole folder, wiki or vault should become real Confluence pages, and stay current as you migrate, import it.
Try Definitive Pages
Import Markdown folders, Git wikis and Obsidian vaults as a Confluence page tree, and re-import to update only what changed. Free for up to 10 users, and it runs entirely on Atlassian.
Other product names are trademarks of their owners.