Confluence Markdown: Does Confluence Support Markdown?

Confluence supports Markdown in one narrow way: the Cloud editor converts **bold**, # , and * as you type them. Pasting a whole Markdown file does not convert. For full Confluence Markdown publishing you need one of three routes. Paste the rendered rich text instead of the raw source, install a Marketplace macro, or push files from Git with a CLI or GitHub Action. This guide covers all three and the reverse direction.

Can I Do Markdown in Confluence? The Three-Way Answer

The confusion around markdown in Confluence comes from three behaviours that look like one feature:

1. Typing shortcuts convert. Type ## and a space in the Cloud editor and you get a Heading 2. Type **text** and it turns bold. This is the "Markdown support" Atlassian advertises.
2. Pasting does not convert. Paste ## Overview from a file and the page shows the literal hashes. The editor only watches keystrokes, not the clipboard.
3. The old Markdown insert is gone from Cloud. The legacy editor had Insert, Markup, Markdown. Atlassian's legacy editor deprecation FAQ gives 1 April 2026 as the date it was fully removed.

Confluence Data Center still has the Markup insert dialog. Cloud pages are stored in Atlassian Document Format (ADF), not Markdown, no matter how they were created, so every markdown to Confluence method below ends in ADF. That is also why Confluence Markdown support will always be partial: the page format itself has no Markdown mode.

Which Markdown Shortcuts Work in the Confluence Cloud Editor?

Atlassian's available markdown commands page lists exactly 18 triggers. This is the full set:

Type	Get
**Bold**	Bold
*Italic*	Italic
~~Strike~~	Strikethrough
Backtick-wrapped text	Inline code
# to ###### plus space	Heading 1 to 6
1. plus space	Numbered list
* plus space	Bulleted list
> plus space	Quote
Three backticks plus space	Code snippet
--- plus space	Divider
[Title](https://a.com)	Link
[] plus space	Action item
<> plus space	Decision

Two of these are Confluence-only: [] creates an action item (a task assigned to a person, not a plain checkbox) and <> creates a decision block. Tables, images, and footnotes have no typing shortcut. Also note that - plus space is not on the list; Confluence documents * for bullets, so use the asterisk if a dash doesn't trigger a list.

How Do You Paste Markdown Into Confluence Without Losing Formatting?

The reliable path for a whole document is to render the Markdown first and paste the rendered result. Confluence's editor accepts rich-text paste from a browser, which is how content arrives from Google Docs and web pages, and a rendered Markdown preview is just another web page.

1. Open the editor and paste your Markdown source into the left pane.
2. Select everything in the right-hand preview pane and copy it.
3. In Confluence, place the cursor on the page and paste.

Headings, paragraphs, bold and italic, lists, links, and simple tables are the elements this route is known for preserving. It is also the fix most often recommended on Atlassian Community threads about markdown on Confluence. Code blocks and nested lists are the ones to check after pasting. Task lists arrive as plain bullets with brackets, because Confluence's action items are a different object.

One limitation: we have not tested every element in every editor version, and Atlassian ships editor changes often. Paste a short sample first and confirm the table and code block survive before you move a 40-page spec. The Markdown table guide explains which table features (alignment, inline code in cells) are worth avoiding when the destination is a wiki.

Copy the preview on the right of this editor and paste it into a Confluence page. Every element in the sample is one we expect to survive.

If you'd rather have the HTML itself, the Markdown to HTML converter produces it; the Markdown to HTML guide explains what the output looks like.

Markdown Macro for Confluence: The Marketplace Route

For teams that want Markdown source to live on the page, a markdown macro for Confluence renders a block of Markdown inside an otherwise normal page. A Marketplace search for "markdown" in Confluence Cloud returns several. Markdown for Confluence provides macros that render Markdown on the page. Markdown Editor for Confluence edits pages in a Markdown editor. Markdown Importer for Confluence Cloud is a Confluence Markdown import app for bulk .md uploads, and Markdown Exporter for Confluence handles the reverse direction.

Macros solve the "keep the source" problem but add a per-user licence and a dependency your admin has to approve. They also render inside the macro's own box, so search, page comments, and inline mentions don't always behave the same as on native content. If your Markdown is written once and rarely edited, render-and-paste is simpler. If engineers will keep editing it in Git, skip the macro too and use a publisher.

Markdown to Confluence From Git: CLI and GitHub Action

The markdown-confluence project converts Markdown to ADF and publishes it with the Confluence REST API. It ships as an Obsidian plugin, an npm CLI, a Docker image, a GitHub Action, and a library, and the repository was still receiving commits in September 2026. The CLI is at version 7.0.0 on npm and requires Node 24.15 or newer.

Setup for the markdown-confluence CLI is a config file plus an API token. Create .markdown-confluence.json in your docs folder:

{
  "confluenceBaseUrl": "https://your-site.atlassian.net",
  "confluenceParentId": "524353",
  "atlassianUserName": "you@example.com",
  "folderToPublish": "docs"
}

Export your Atlassian API token as ATLASSIAN_API_TOKEN, then run the CLI. The README uses vp dlx; npx resolves the same package:

export ATLASSIAN_API_TOKEN="your-token"
npx @markdown-confluence/cli

Every .md file under docs becomes a child page of the parent ID, and re-running the publisher updates the pages in place. The markdown-confluence GitHub Action wraps the same code:

- name: Publish Markdown to Confluence
  uses: markdown-confluence/publish-action@v7
  with:
    confluenceBaseUrl: https://your-site.atlassian.net
    confluenceParentId: "524353"
    atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
    atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
    folderToPublish: docs

The markdown-confluence CLI also has to-adf and to-markdown subcommands for one-off conversions of a file or a page ID. Running one is the quickest way to see what the conversion keeps and drops. Mermaid and other diagram fences go through a Kroki server if you configure one.

If you'd rather call the API yourself, the Confluence Cloud REST API v2 create-page endpoint takes a body with a representation of storage or atlas_doc_format. Converting Markdown to ADF by hand is the hard part, which is why the publisher exists.

Can I Export a Confluence Page as Markdown?

Not directly. Atlassian's export documentation lists Word and PDF for a single page, and PDF, CSV, HTML, and XML for a whole space. Word exports open only in Microsoft Word. So the reverse direction is a two-step job: export to HTML (space) or Word (page), then convert.

For a page, export to Word and run it through the Markdown to Word guide in reverse using our DOCX to Markdown tool. For a space, the HTML export plus the HTML to Markdown converter handles many pages at once. The markdown-confluence CLI's to-markdown --page 123456 subcommand pulls one page straight from the API as Markdown, and Marketplace exporters do it in bulk. The Confluence to Markdown post walks through each option step by step.

Common Markdown Confluence Mistakes

Pasting raw Markdown and expecting conversion. The editor converts typed shortcuts only. Render first, or use a macro or publisher.

Assuming Cloud and Data Center behave the same. Data Center still offers Insert, Markup, Markdown. Cloud removed the legacy editor entirely in April 2026. Confluence and Markdown documentation from before that date often describes Cloud features that no longer exist.

Publishing with a personal token in CI. The GitHub Action needs an API token stored as a repository secret. Use a service account so pages don't disappear or lose their author when someone leaves.

Markdown Confluence FAQ

The honest summary: Confluence understands Markdown shortcuts while you type and nothing more. For real Confluence Markdown work, render your file in the editor and paste the preview. Add a macro if the source must live on the page, or automate publishing from Git with the CLI. Whichever route you pick, test one page first, because ADF is not Markdown and a few elements always need a manual touch.