If your team writes documentation as markdown in a repository, and the rest of the company lives in Confluence, you will eventually be asked to connect the two. There are four ways to do it. They produce genuinely different results, and the difference does not show up on day one. It shows up months later, usually when somebody cannot find a document they know exists.
Here is each route, what it actually costs, and how to pick.
Disclosure up front: I build one of the options below, and the section at the end says where it is the wrong choice.
First, the thing that decides everything else
Before comparing tools, decide whether these documents need to be findable by Confluence search.
If they do, that single question eliminates more options than anything else on this page, so it is worth understanding the mechanism rather than taking anyone's word for it.
Confluence indexes the content of a page. A dynamic content macro, which is how most Marketplace apps render external content, draws that content inside an iframe. Content inside an iframe is not picked up by Confluence search. So a page can look completely correct on screen and still be invisible to a search for a phrase inside it.
That is not true of every app. An app can push text into the search index on purpose, using content properties with CQL extractions, or macro parameter indexing. Some do. The problem is that a Marketplace listing will not usually tell you, and the behaviour is identical until you search.
A page created through the Confluence REST API has no such issue. It is an ordinary page and it is indexed like one.
The test takes two minutes and I would run it before committing to any route below. Publish one document. Then search Confluence for a word that appears only in the middle of that document, not in the title. If the page comes back, you are fine. If it does not, you have just saved yourself a migration.
Route 1: paste it
Confluence Cloud converts markdown when you paste it into the editor. For a handful of documents that will never change, this is the correct answer and everything below is overengineering.
What it costs: your time, every time anything changes. It stops being viable the moment the documents have a lifespan.
Route 2: a macro app
Apps like Include from GitHub to Confluence, or the various markdown macros, let you point a Confluence page at a file in a repository and render it.
What is good: fast to set up, no pipeline, and the file stays in the repository as the source of truth.
What it costs: the search question above. Check it before you roll it out to a team, because it is the whole reason the docs were going into Confluence.
There is a second thing worth knowing. Rendering a file is not the same as reproducing a folder of files. If you have eighty documents in a tree, you are adding eighty macros by hand and maintaining that tree yourself.
Route 3: a script or a CI job
This is the route most engineers reach for, and it is a genuinely good one.
Tools that already exist: mark, confluence-junction, go-markdown2confluence, and a well travelled pattern of doing it from a GitHub Action against the REST API.
What is good: these create real pages, so search works. You control everything. It is free. If your team is comfortable owning it, this is a legitimate permanent answer, and I would not try to talk anyone out of it.
What it costs, and this is the part that gets underestimated: you now own a pipeline. A token that expires and has to be rotated. A job that can fail quietly, so the pages drift out of date without anyone noticing, which is worse than not having them. And a piece of internal tooling that one person understands and that becomes a problem when that person changes team.
If you have a platform team, this cost is small. If the documentation is owned by two people who also have day jobs, it is not.
Route 4: a sync app
An app that connects to the repository directly, reads the markdown, and creates real Confluence pages, then keeps doing it.
What is good: the result of route 3 without owning the pipeline. Real pages, so search works. The folder tree is rebuilt for you.
What it costs: money, and trusting a third party with a token and with write access to a space.
Things to check before you pick one
All of these vary between apps.
- Does it create real pages, or render into a macro? Run the search test.
- Does it hold a delete permission? An app that can write into your wiki can usually also empty it. Ask what happens when a file is removed from the repository.
- Is a second run safe? Re-running should update the same pages, not create a second copy of everything.
- Will it overwrite a page a person wrote? A title collision should stop the sync, not silently replace someone's work.
- How does it authenticate to private repositories, and can the token be scoped to one repo?
- Schedule or webhook? A scheduled sync means a delay after every push. A webhook means near instant. Decide which you need, because it will rule things out.
How to choose, briefly
- A few documents that will not change: paste them.
- You need the current file visible on a page and search does not matter: macro app.
- You have a platform team and want full control: script or GitHub Action.
- You want real searchable pages and do not want to own a pipeline: sync app.
Disclosure
I built one of the route 4 apps, Repo Docs for Confluence, which is on the Atlassian Marketplace. I wrote this because the comparison did not exist and I had to work it out anyway.
It creates ordinary Confluence pages, so search finds words inside them. It rebuilds the folder tree as parent pages, and it names pages from front matter or the first heading rather than the file name. Re-running updates the same pages. It requests no delete permission at all, so when a file leaves the repository it tells you which page has nothing behind it and leaves the page alone. It refuses to overwrite a page it did not create. It runs on Atlassian Forge, so no server of mine receives your documents. Free up to 10 users.
Two cases where it is the wrong choice, and I would rather say so here than in a support ticket.
If you need pages updated within seconds of a push, it syncs hourly, and a webhook based tool or your own GitHub Action will serve you better.
If you already have a pipeline that works and somebody who maintains it, you have already paid the cost of route 3. There is nothing here worth switching for.
