How to Write Markdown in Confluence Without Losing Formatting

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 — it doesn't interpret markdown syntax natively.

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 spending time manually reformatting content every time it moves.

Markdown Renderer for Confluence solves this directly: add the macro to a page, write markdown inside it, and it renders live. No conversion, no reformatting, no copy-paste friction.

---

Why Confluence Doesn't Support Markdown Natively

Confluence uses a proprietary storage format called Confluence Storage Format (XHTML-based). The editor works at that level — not at the markdown level. When you type in the editor, you're generating structured XML under the hood, not markdown.

There's no built-in way to write **bold** and have it render as bold. You'd have to use the editor's toolbar, keyboard shortcuts, or Confluence macros. That workflow doesn't fit teams who live in markdown — documentation-as-code practitioners, developers writing runbooks, or technical writers migrating content from GitHub or Notion.

---

What Markdown Renderer Does

Markdown Renderer for Confluence is a Forge-native macro that renders markdown inline on a Confluence page. You insert the macro, paste or write your markdown inside it, and the page displays the rendered output — headings, tables, code blocks, math, and all.

The key behaviors:

• Live rendering — what you write in the macro body renders as formatted content on save
• GFM support — GitHub Flavored Markdown is fully supported, including tables, task lists, and strikethrough
• Code blocks with syntax highlighting — fenced code blocks with language identifiers render with proper highlighting
• Math support — inline and block LaTeX expressions via $...$ and $$...$$ syntax
• No external requests — everything runs inside Confluence via Forge; your content never leaves Atlassian infrastructure

---

How to Insert the Macro

1. Open or create a Confluence page
2. In the editor, type / to open the macro browser
3. Search for Markdown Renderer
4. Select it — a macro placeholder appears on the page
5. Click into the macro body and write or paste your markdown
6. Save the page

That's it. The macro renders on save, and any editor who opens the page for editing sees the raw markdown in the macro body — editable as plain text.

---

Markdown Features Supported

Headings and Text

Standard ATX-style headings (#, ##, ###) render as Confluence heading levels. Emphasis (*italic*, **bold**), strikethrough (~~text~~), and inline code (code) all work as expected.

Tables

GFM pipe tables render correctly, including 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 — content types that are painful to build in the Confluence native editor.

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 automatically based on the language tag.

Math

If you're writing technical documentation that includes equations, the macro supports LaTeX math syntax:

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

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

This uses the same rendering pipeline as LaTeX Math for Confluence — equations render cleanly without needing a separate macro for simple cases.

Task Lists

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

These render as visual checkboxes, making them useful for runbooks, checklists, and release notes embedded in Confluence pages.

---

Practical Tips for Technical Writers

Keep your source in markdown. If you're maintaining documentation in a Git repo, the Markdown Renderer macro lets you paste the current content into Confluence without reformatting it. When the source changes, you update the macro body. It's not automated sync (for that, use Markdown Importer's REST API), but it's fast enough for most workflows.

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 page layouts, comments, or Confluence-specific macros, and drop into the markdown macro for content-heavy sections.

Watch your frontmatter. If you paste markdown from a file that has YAML frontmatter (--- block at the top), strip it before pasting — the renderer will display it as text. Frontmatter is handled at import time by Markdown Importer, not at render time.

Tables with many columns. Confluence pages have a fixed width. Very wide markdown tables can overflow the macro boundary. Either reduce the column count or apply a full-width page layout before inserting the macro.

---

When to Use Markdown Renderer vs Markdown Importer

These are different tools for different problems:

Scenario	Tool
Write markdown inline on a Confluence page	Markdown Renderer
Bring in a file, folder, or GitHub repo as Confluence pages	Markdown Importer
Automate doc sync via CI/CD	Markdown Importer (REST API)
Live markdown editing in Confluence	Markdown Renderer

If your workflow is "write in markdown, publish to Confluence," you likely want both.

---

Getting Started

Install Markdown Renderer for Confluence from the Atlassian Marketplace. It's Forge-native, so no external server connections, no CSP exceptions, and no admin firewall approvals needed.

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

---

Questions? Reach out via our support portal.