How to Write Markdown in Confluence Without Losing Formatting

Short answer: Confluence's editor doesn't render a pasted Markdown document, so the formatting is lost. To write Markdown and see it rendered, add a Markdown macro: with Markdown Macro+ for Confluence, type /markdown while editing, write or paste Markdown in the left pane, check the live preview and click Save. Tables, task lists, code blocks and math render on the page.

If you've ever pasted Markdown into a Confluence page, you know what happens: the formatting disappears and you're left with raw asterisks, backticks, and pound signs. Confluence has its own editor, and it doesn't treat a pasted Markdown document as Markdown.

That's a real problem for technical writers and engineers who write in Markdown by default. You end up maintaining two versions of everything, or reformatting content every time it moves.

Markdown Macro+ for Confluence (formerly Markdown Renderer) solves this directly: add the macro to a page, write Markdown in its editor with a live preview, and the page shows the rendered result.

Why Confluence Doesn't Handle Markdown Natively

Confluence stores pages in its own structured format, and the editor works at that level rather than at the Markdown level. The editor understands some Markdown-style shortcuts as you type, but a pasted Markdown file with tables, fenced code blocks and front matter doesn't come through as formatted content. Confluence's own text syntax, wiki markup, isn't accepted by the Cloud editor either; see Confluence markup vs Markdown for how the two compare.

That workflow doesn't fit teams who live in Markdown: docs-as-code practitioners, developers writing runbooks, or technical writers bringing content over from GitHub or Notion.

What Markdown Macro Does

Markdown Macro+ for Confluence is a macro you add to any page. Inside it, you write Markdown in an editor on the left and see a real-time preview on the right. When you save, the page displays the rendered output.

The key behaviors:

Split-view editor: write on the left, live preview on the right, then click Save
GitHub Flavored Markdown: tables, task lists, strikethrough and fenced code blocks
Code blocks with syntax highlighting: based on the language tag
Math: inline and block expressions, rendered with KaTeX
Confluence attachments: insert images and files that are attached in Confluence from the editor toolbar
Templates: reuse common Markdown content across pages

How to Insert the Macro

Open or create a Confluence page and start editing
Type /markdown and select the Markdown macro from the list
Write or paste your Markdown in the left pane
Check the live preview in the right pane
Click Save in the macro editor, then publish the page

To change the content later, edit the macro and the editor opens again with your Markdown source.

Markdown Features Supported

For the full syntax of each element, with an example to copy, see the Markdown syntax reference.

Headings and Text

Standard headings (#, ##, ###), emphasis (*italic*, **bold**), strikethrough (~~text~~) and inline code (`code`) all render as you'd expect. (For the shortcuts in Confluence's own editor, see inline code and code blocks in Confluence.)

Tables

GFM pipe tables render with column alignment:

| Method | Endpoint         | Auth     |
| ------ | ---------------- | -------- |
| GET    | /api/v1/users    | Required |
| POST   | /api/v1/sessions | None     |

This is particularly useful for API documentation and reference tables, which are tedious to build in the native editor. Keep tables simple: merged cells and other advanced table features may not render perfectly.

Code Blocks

Fenced code blocks with language identifiers:

```python
def parse_webhook(payload: dict) -> Event:
    return Event(
        type=payload["type"],
        data=payload.get("data", {}),
    )
```

Syntax highlighting is applied based on the language tag. The code blocks docs list the supported languages.

Math

For technical documentation with equations, the macro supports math syntax using single dollar signs for inline expressions and double dollar signs for blocks:

The time complexity is $O(n \log n)$.

$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$

Very complex expressions may not render as expected, so check them in the preview. If equations are the main content of a page, a dedicated macro such as LaTeX Math for Confluence gives you separate inline and block math macros with their own editor.

Task Lists

- [x] Write the API spec
- [x] Review with backend team
- [ ] Update the runbook
- [ ] Notify stakeholders

These render as checkboxes, which is handy for runbooks, checklists and release notes. Some GitHub-specific task list and emoji behavior may look slightly different from GitHub.

Images

Images and files need to be stored in Confluence. Because of Atlassian's data egress policy, the macro can't load files from external URLs, so upload them to Confluence first and insert them with the attachment button in the toolbar:

![Architecture diagram](attachment:architecture.png)

Practical Tips for Technical Writers

Keep your source in Markdown. If your documentation lives in a Git repo, you can paste the current content into the macro without reformatting it. When the source changes, update the macro. It's not an automated sync (for that, see how to sync GitHub docs to Confluence automatically), but it's quick for occasional updates.

Use one macro per logical section. You don't have to put an entire page inside a single macro. Mix native Confluence content with Markdown macro blocks: use the native editor for layouts and Confluence-specific macros, and the Markdown macro for content-heavy sections.

Strip front matter before pasting. If your file starts with a YAML front matter block (--- at the top), remove it before pasting so it doesn't end up in the rendered output.

Split very long documents. Rendering very large Markdown documents can slow the page down. Several macros or several pages work better than one huge block.

When to Use Markdown Macro vs Markdown Importer

These are different tools for different problems:

Scenario	Tool
Write Markdown inline on a Confluence page, with live preview	Markdown Macro+ for Confluence
Turn `.md` files or a ZIP of a docs folder into native Confluence pages	Markdown Importer for Confluence
Push docs from a repo to Confluence via CI/CD	Markdown Importer for Confluence (REST API)

Markdown Macro keeps the content as Markdown inside the page. Markdown Importer converts Markdown into regular Confluence content that anyone can then edit in the native editor. If your workflow is "write in Markdown, publish to Confluence", you may want both.

Getting Started

Install Markdown Macro+ for Confluence from the Atlassian Marketplace.

Full documentation is at /docs/markdown-renderer-for-confluence.

Questions? Reach out via our support portal.