# Import Markdown into Confluence: Paste, GitHub, .md Files

September 24, 2026 ·

<!-- -->

3 min read

[NGPilot](https://ngpilot.com)

Every team has Markdown lying around that Confluence needs: the README that became the service doc, the design doc drafted as a pull-request description, the runbook that lives in the repo. And every attempt to move it hits the same wall — Confluence's default editor does not parse Markdown. Paste a .md document and you get a wall of pipes, backticks, and asterisks that looks exactly like what it is: text nobody formatted.

The macro route dissolves the wall. Paste the document into a Markdown macro that actually parses it, watch it render in the preview pane, publish. This page is the workflow, end to end.

**Quick answer:** To import Markdown into Confluence, install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence), insert its Markdown macro on the page, and paste your .md content into the source pane. GFM tables, code fences, Mermaid diagrams, and KaTeX math all render live in the split-pane preview — then publish. The source stays editable, so updates are text edits, not re-imports. Free for up to 10 users.

## The Three Sources This Covers[​](#the-three-sources-this-covers "Direct link to The Three Sources This Covers")

**1. A README from GitHub.** Copy the rendered README's raw content (or `git cat-file` it, or open the raw view), paste into the macro. Tables, code fences, and links arrive intact — the document keeps its structure on the way in.

**2. An .md file from anywhere.** Notion export, Obsidian note, a docs folder in the repo: open the file, select all, paste. Tools that export non-standard syntax need a quick cleanup pass first — after that it is one paste.

**3. Drafts from other contexts.** The pull-request description that grew into a design doc, the incident timeline written in a text editor, the LLM-assisted draft. If it is Markdown, the paste is the same.

## What Survives the Paste[​](#what-survives-the-paste "Direct link to What Survives the Paste")

| Content in your .md                   | What renders in Confluence                       |
| ------------------------------------- | ------------------------------------------------ |
| `# Headings`, lists, emphasis         | Native Confluence structure                      |
| GFM pipe tables                       | Real tables                                      |
| ` ```lang ` code fences               | Highlighted blocks, 190+ languages, copy buttons |
| ` ```mermaid ` / ` ```zenuml ` fences | Rendered diagrams                                |
| ` ```katex ` / `$...$` math           | Rendered equations                               |
| Standard links and images             | Links render; images follow Markdown link syntax |

The closer the source is to a standard README, the closer to zero cleanup. Well-formed documents go in with no touch-ups at all.

## The Workflow on a Real Page[​](#the-workflow-on-a-real-page "Direct link to The Workflow on a Real Page")

1. `/markdown` on the target page → the macro's split pane opens.
2. Paste the document into the left pane — the right pane renders as it lands.
3. Scroll to check the long sections: **bidirectional scroll sync** keeps source and preview locked together, so on a 400-line document you are never hunting for where you are.
4. Fix the two or three spots every migration has (a table with a stray pipe, a fence missing its language tag) — each fix is visible in the preview instantly.
5. Publish.

The published page keeps the Markdown as source. When the service's retry policy changes next quarter, you edit the sentence — you do not re-run an import. Install [Enhanced Markdown for Confluence](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence) and move the first document over. Free for up to 10 users.

## Related Guides[​](#related-guides "Direct link to Related Guides")

* [How to Write Markdown in Confluence](/blog/how-to-write-markdown-in-confluence.md) — the syntax reference for what you paste
* [Confluence Markdown Tables](/blog/confluence-markdown-tables.md) — the table syntax in depth
* [Markdown Meeting Notes Template for Confluence](/blog/markdown-meeting-notes-confluence.md) — if the document you are importing is a notes page, start from the template instead

Try <!-- -->Enhanced Markdown for Confluence

Write Markdown with live split preview, Mermaid diagrams, KaTeX/LaTeX math, and 190+ code languages — all in one macro, free for up to 10 users.

[Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1237026/enhanced-markdown-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=enhanced-markdown-for-confluence)

## Related guides

* [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md)
* [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md)
* [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md)
* [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md)

Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links)

**Tags:**

* [confluence](/blog/tags/confluence.md)
* [markdown](/blog/tags/markdown.md)
* [import](/blog/tags/import.md)
* [migration](/blog/tags/migration.md)
* [github](/blog/tags/github.md)
* [how-to](/blog/tags/how-to.md)
* [developer-tools](/blog/tags/developer-tools.md)