Edit with Markdown

Edit with Markdown opens a whole Confluence page as Markdown. You edit the Markdown on the left, and the right side shows the page exactly as it will be published. When you publish, the page is saved as normal Confluence content, not as a macro, so it looks and behaves like any other page.

It works on pages and blog posts.

Open it

There are two ways in:

• The byline: click Edit with Markdown under the page title.
• The ••• menu: open More actions at the top of the page and choose Edit with Markdown.

You are then asked what you want to do:

• Edit this page (or Edit this blog post): change it in Markdown, with the page preview beside it.
• New child page: write a new page in Markdown under this one. From a blog post this choice is New page, which creates a page at the top of the space. See New page from Markdown.

The editor

• Title: edit the page title at the top. A page needs a title of up to 255 characters.
• Markdown: the left pane. It has the same toolbar as the macro editor, plus Markdown Macro+ block, and you can insert a .md file or download the page as .md.
• Page preview: the right pane shows what will be published, updated as you type.
• Resize: drag the handle between the panes. Each side can take between a quarter and three quarters of the width, and the split is remembered.
• Start from a template: pick a template to insert it at the cursor. See Templates and variables.

The footer has a Version note field ("What changed?"), and the Cancel, Save draft and Publish buttons. If you leave the version note empty, the version is noted as "Edited with Markdown Macro+". Save draft and Publish stay disabled until you change something.

How a page becomes Markdown

Standard content is written as plain Markdown:

• headings, paragraphs, bold, italic, strikethrough, inline code and links
• bulleted, numbered and task lists
• quotes and horizontal rules
• code blocks with their language
• simple tables: one header row, no merged cells, one paragraph per cell
• images shown from a web address, as ![alt](https://...)

Confluence elements that Markdown has no syntax for use a small page dialect:

Confluence element	Write it as
Info, note, warning, error and success panels	> [!INFO], > [!NOTE], > [!WARNING], > [!ERROR], > [!SUCCESS]
Decision list	> [!DECISION] followed by - item lines
Expand	:::expand Title on one line, the content, then :::
Status lozenge	{{status:TEXT color}}, colour one of neutral, purple, blue, red, yellow, green
Date	{{date:2026-11-15}}
Image from a web address	, sized with "width=400px" or "width=50%" after the address

The GitHub alert names also work: [!TIP] becomes a success panel, [!IMPORTANT] an info panel and [!CAUTION] an error panel. Note that in Edit with Markdown [!NOTE] is Confluence's purple note panel, while in the macro it is the blue info style. Expands can be nested. To write a literal {{, type \{\{.

Task and decision ids are kept, so Confluence task reports keep working after you publish.

Content that stays as it is

Some content can't be written in Markdown. Edit with Markdown keeps it on its own line, for example {{keep:a1 Image: diagram.png}}, and publishes it exactly as it was. This covers:

• images and files uploaded to Confluence
• macros from other apps
• page layouts
• smart links (link cards)
• @mentions
• custom panels
• complex tables, such as tables with merged cells, rich cells or no header row

A notice above the editor lists what is kept. You can move a keep line or delete it, but don't edit it. In the preview it shows as a locked card; to change that content, use the Confluence editor.

Formatting Markdown can't hold

Some formatting has no Markdown equivalent and is removed when you publish:

• underline, text colour and highlight colour
• subscript and superscript
• inline comment highlights
• text alignment and indentation
• full-width and custom-width layouts
• custom table widths and layouts, numbered table rows and cell colours

When a page has any of these, a warning lists them with a checkbox. Tick it to publish anyway, or cancel and keep using the Confluence editor for that page.

Markdown Macro+ macros on the page

Each Markdown Macro+ macro on the page shows up in the editor as a markdown-macro fenced block:

````markdown-macro
## Release checklist

- [ ] Tag the build
````

• Edit the content of the block to update that macro, including its text in Confluence search.
• Delete the block to remove the macro.
• Click Markdown Macro+ block in the toolbar to add a new macro.

The preview draws each block with the macro's own renderer, so math, Mermaid diagrams and callouts look as they will on the page. A plain ```markdown code block is just a code block, not a macro.

Drafts

• Save draft saves your changes as a draft of the page without publishing them. It replaces any existing draft.
• If someone has unpublished changes in the Confluence editor, you are asked first which version to edit: Continue from the draft (recommended) or Edit the published version.
• If you edit the published version while a draft exists, a warning with a checkbox appears before you publish, because publishing could replace that person's changes. Tick it to publish anyway, or save yours as a draft instead.

Conflicts

If someone publishes a newer version while you are editing, publishing stops with a message saying who changed the page. Use Copy my Markdown to keep your work, then Reload the page and apply your changes again.

Permissions

You need permission to edit the page in Confluence. Edit with Markdown uses the app's permission to read and update pages; if a Confluence admin hasn't approved that yet, see Updates waiting for approval.

Limitations

• Images are added by web address (https://...). To upload an image file, use the Confluence editor. An image in a heading, task or decision is published as a link to it.
• The page preview may not be able to show an image from another website. It shows a card with the image's address instead, and the published page shows the image.
• Math, Mermaid diagrams, [[toc]], :shortcode: emoji and footnotes typed directly into the page are not converted. Put them in a Markdown Macro+ block instead, where they render as in the macro.
• Raw HTML is shown as text.

See Known issues for the full list.