# How to Write Markdown in Confluence — Syntax, Tables & Code Blocks May 2, 2026 · 12 min read [NGPilot](https://ngpilot.com) Who should read this * **Developers and tech writers** who want to write Markdown in Confluence instead of the WYSIWYG editor * **Teams migrating** README files, docs repos, or API references into Confluence * **Anyone** who needs Mermaid diagrams or LaTeX math inside Markdown content What you'll learn 1. Whether Confluence supports Markdown natively (and why it doesn't) 2. How to write Markdown with live preview, including code blocks, tables, and Mermaid 3. How Markdown content behaves after publish (search, exports, permissions) 4. When to use Markdown vs. Confluence's native WYSIWYG editor Confluence's built-in editor is strictly WYSIWYG — there is no native Markdown editor. For teams who already write in Markdown (README files, docs repos, pull request descriptions), that means manually reformatting every doc through toolbar buttons, losing time and introducing inconsistencies. **Enhanced Markdown for Confluence** solves this by embedding a full Markdown editor with live split preview directly inside Confluence — and it renders Mermaid diagrams, KaTeX/LaTeX math, and 190+ code-highlighted languages, all in one macro. This FAQ answers the questions teams ask most often about writing Markdown in Confluence. *** ## Frequently Asked Questions[​](#frequently-asked-questions "Direct link to Frequently Asked Questions") ### 1. Does Confluence support Markdown natively?[​](#1-does-confluence-support-markdown-natively "Direct link to 1. Does Confluence support Markdown natively?") No. Confluence's built-in editor is entirely WYSIWYG (What You See Is What You Get). You format content using toolbar buttons, keyboard shortcuts, and slash commands -- not by writing markup. While Confluence can display Markdown content that has been imported or embedded through specific macros, there is no first-party Markdown editor where you write and edit page content in Markdown syntax directly. This is a significant limitation for developer teams. Most developers write in Markdown every day: README files in Git repositories, pull request descriptions on GitHub or Bitbucket, documentation in static site generators like Docusaurus or MkDocs, and comments in Jira. Having to switch from Markdown to a visual editor when moving content into Confluence adds friction and slows down the documentation process. **Enhanced Markdown for Confluence** fills this gap. It installs from the Atlassian Marketplace and adds a dedicated Markdown editing macro to your Confluence instance. Once installed, any user on your Confluence site can insert a Markdown block by typing `/enhanced markdown` in the editor and selecting the macro. The macro opens a full-featured Markdown editing environment right inside the Confluence page, with a live split preview (powered by the Quikdown engine) so you see the rendered output — including Mermaid diagrams and LaTeX math — as you type. The key advantage is that the rendered output becomes standard Confluence content. It participates in Confluence search indexing, respects page permissions, works with exports, and integrates with all of Confluence's platform features just like any other page content. ### 2. How does Enhanced Markdown for Confluence work?[​](#2-how-does-enhanced-markdown-for-confluence-work "Direct link to 2. How does Enhanced Markdown for Confluence work?") Enhanced Markdown for Confluence operates as a Confluence macro that you insert into any page. Here is the step-by-step workflow: 1. **Edit a Confluence page** and place your cursor where you want the Markdown content to appear. 2. **Type `/enhanced markdown`** in the editor and select **Enhanced Markdown for Confluence** from the macro list. 3. **Write or paste your Markdown** into the editor that opens. The editor provides a live split preview (powered by the Quikdown engine), so you see the rendered output — including Mermaid diagrams and LaTeX math — as you type. 4. **Preview in WYSIWYG mode.** Switch to WYSIWYG mode at any time to see how the rendered content will look, so you can catch formatting issues before saving. 5. **Click Save** to render the Markdown onto the page. The content is stored in standard Confluence storage format. 6. **Re-edit anytime.** Click on an existing Enhanced Markdown macro and select Edit to reopen the editor. Your Markdown source is fully preserved, so you can continue editing from where you left off. Under the hood, the app converts your Markdown into Confluence's native storage format when you save. This means the rendered content is fully compatible with Confluence's export engines (PDF, HTML, Word), search indexing, macro processing, and page permissions. From Confluence's perspective, the output is no different from content created in the native editor. The editor also supports dark mode automatically. When a user has Confluence's dark theme enabled, the Markdown macro adapts its appearance to match, ensuring a consistent visual experience. For a complete walkthrough of all features and configuration options, see the [Enhanced Markdown for Confluence usage guide](/docs/Enhanced-Markdown-for-Confluence/usage.md). ### 3. What Markdown syntax does Enhanced Markdown for Confluence support?[​](#3-what-markdown-syntax-does-enhanced-markdown-for-confluence-support "Direct link to 3. What Markdown syntax does Enhanced Markdown for Confluence support?") The editor supports comprehensive Markdown syntax covering both the CommonMark specification and GitHub Flavored Markdown (GFM) extensions. Here is a detailed breakdown of what is available: **Core formatting:** * Headings (H1 through H6 using `#` prefix) * Bold (`**text**`), italic (`*text*`), and strikethrough (`~~text~~`) * Ordered and unordered lists with nesting * Task lists with checkboxes (`- [ ]` and `- [x]`) * Links (inline and reference-style) * Blockquotes (`>`) — see the [block quote in Confluence guide](/blog/block-quote-confluence.md) for nesting and attribution * Horizontal rules (`---` or `***`) **GitHub Flavored Markdown extensions:** * Pipe tables with column alignment * Fenced code blocks with language-specific syntax highlighting * Task lists **Advanced features beyond standard Markdown:** * Table merged cells for complex table layouts * Color syntax with visual color previews * Chart embedding * PlantUML diagram rendering for UML diagrams (sequence, class, use case, and more) This syntax coverage means that virtually any Markdown content you write in GitHub, VS Code, or your documentation toolchain will render correctly when pasted into Enhanced Markdown for Confluence. You do not need to learn Confluence-specific syntax or adjust your writing habits. ### 4. Can I use code blocks with syntax highlighting in Markdown content?[​](#4-can-i-use-code-blocks-with-syntax-highlighting-in-markdown-content "Direct link to 4. Can I use code blocks with syntax highlighting in Markdown content?") Yes, code blocks are one of the strongest features of Enhanced Markdown for Confluence. The editor supports fenced code blocks with language identifiers, and they render with syntax highlighting for dozens of programming languages. To create a code block, wrap your code with triple backticks and specify the language: ```` ```python def calculate_total(items): total = sum(item.price * item.quantity for item in items) return round(total, 2) ``` ```` ```` ```javascript const fetchData = async (endpoint) => { const response = await fetch(endpoint); return response.json(); }; ``` ```` The syntax highlighting engine automatically applies language-aware color formatting based on the identifier you specify. Common identifiers include `python`, `javascript`, `java`, `go`, `rust`, `typescript`, `sql`, `bash`, `json`, `yaml`, `xml`, `html`, `css`, and many more. Code blocks also adapt to Confluence's theme. When a user views the page in dark mode, the code block rendering adjusts to maintain readability and contrast. This ensures that technical content looks professional regardless of the viewer's theme preference. For teams that need even more advanced code display features -- such as configurable line numbers, minimap navigation, and the Monaco editor experience -- Enhanced Markdown for Confluence works alongside Modern Code Blocks for Confluence. You can learn more about advanced code display options in the [advanced code blocks guide](/blog/advanced-code-blocks-confluence.md). ### 5. How do tables and images work in the Markdown editor?[​](#5-how-do-tables-and-images-work-in-the-markdown-editor "Direct link to 5. How do tables and images work in the Markdown editor?") **Tables** are supported through standard Markdown pipe syntax. You create tables by separating columns with pipe characters and defining the header row with separator dashes: ``` | Feature | Supported | Notes | |---------|-----------|-------| | Basic tables | Yes | Standard pipe syntax | | Column alignment | Yes | Use `:---`, `:---:`, `---:` | | Merged cells | Yes | Beyond standard Markdown | ``` Column alignment is controlled by adding colons to the separator row: `:---` for left-aligned, `:---:` for center-aligned, and `---:` for right-aligned. Enhanced Markdown for Confluence goes beyond standard Markdown table support by offering **merged cells**. This allows you to create complex table layouts with cells that span multiple rows or columns -- something that standard Markdown cannot express but that is common in project status reports, comparison matrices, and detailed technical specifications. **Images** are added using standard Markdown image syntax: ``` ![Alt text describing the image](https://example.com/image.png) ``` Images render inline on the Confluence page. Alt text is preserved for accessibility. You can reference externally hosted images or images that have been attached to the Confluence page. The rendered images behave like native Confluence image embeds -- they display at an appropriate size within the page layout and are accessible through the page's attachment management. ### 6. How does the Markdown editor compare to Confluence's native WYSIWYG editor?[​](#6-how-does-the-markdown-editor-compare-to-confluences-native-wysiwyg-editor "Direct link to 6. How does the Markdown editor compare to Confluence's native WYSIWYG editor?") The two editors serve different audiences and workflows. Here is a detailed comparison: **Editing experience.** The native Confluence editor is toolbar-driven. You select text and click buttons to apply formatting, or use slash commands to insert elements. Enhanced Markdown for Confluence is keyboard-centric — you type formatting syntax directly, which is significantly faster for users who are comfortable with Markdown. The editor also provides a live split preview (powered by the Quikdown engine), so you see exactly how the rendered page will look — including Mermaid diagrams, LaTeX math, and syntax-highlighted code — as you write. **Content portability.** Markdown content is plain text. You can copy it out of Confluence and paste it into GitHub, VS Code, a static site generator, or any other Markdown-compatible tool without reformatting. WYSIWYG content is stored in Confluence's proprietary XML-based storage format, which is difficult to extract and reuse outside of Confluence. **Version control compatibility.** Plain-text Markdown files diff cleanly in Git and other version control systems. You can review changes line by line in a pull request. WYSIWYG content stored in Confluence's storage format produces XML diffs that are nearly impossible to review manually. If your documentation workflow involves Git-based review processes, Markdown is the clear winner. **Learning curve.** WYSIWYG editing has essentially no learning curve -- anyone can click a Bold button. Markdown requires learning a lightweight syntax, but for developers and technical writers who already know it, there is zero additional learning required. The Markdown editor's dual-mode design (raw Markdown and WYSIWYG) also provides a safety net for users who are still learning the syntax. **Macro support.** The native editor has access to the full Confluence macro library through the macro browser. Enhanced Markdown for Confluence supports macro syntax for commonly used macros like info panels, tables of contents, and code blocks. For pages that rely heavily on specialized Confluence macros, the native editor may be more practical. Many teams use a hybrid approach: Markdown for the body content and native Confluence macros for specialized elements. | Feature | Enhanced Markdown | Native WYSIWYG | | ------------------------ | -------------------------------- | ------------------------------ | | Editing mode | Raw Markdown + WYSIWYG | WYSIWYG only | | Keyboard-centric writing | Yes | Partial (shortcuts) | | Live preview | Yes — switch to WYSIWYG mode | Native (inline) | | Code syntax highlighting | Fenced blocks with language tags | Code block macro | | Table merged cells | Supported | Supported | | PlantUML diagrams | Supported | Requires separate macro | | Dark mode adaptation | Automatic | Automatic | | Content portability | Plain text, works everywhere | Confluence storage format only | | Version control diffs | Clean, line-by-line | XML, hard to review | | Full macro library | Common macros supported | All macros available | | Re-editing source | Source preserved | N/A (visual) | *** ## Markdown Syntax Quick Reference[​](#markdown-syntax-quick-reference "Direct link to Markdown Syntax Quick Reference") Here is a quick reference for the Markdown syntax supported by Enhanced Markdown for Confluence. Use this table as a cheat sheet when writing content. | Element | Syntax | Example | | ---------------------- | --------------------------- | ------------------------------- | | Heading H1 | `# text` | `# Project Overview` | | Heading H2 | `## text` | `## Installation` | | Heading H3 | `### text` | `### Prerequisites` | | Bold | `**text**` | `**important note**` | | Italic | `*text*` | `*emphasis*` | | Strikethrough | `~~text~~` | `~~deprecated~~` | | Unordered list | `- item` | `- First item` | | Ordered list | `1. item` | `1. First step` | | Task list (incomplete) | `- [ ] task` | `- [ ] Write tests` | | Task list (complete) | `- [x] task` | `- [x] Deploy to staging` | | Link | `[text](url)` | `[NGPILOT](https://ngpilot.io)` | | Image | `![alt](url)` | `![Logo](/img/logo.png)` | | Inline code | `` `code` `` | `` `console.log()` `` | | Code block | Triple backticks + language | See code block examples above | | Blockquote | `> text` | `> This is a note` | | Horizontal rule | `---` | `---` | | Table | Pipe syntax with header row | See table examples above | *** ## Tips for Getting the Most Out of Markdown in Confluence[​](#tips-for-getting-the-most-out-of-markdown-in-confluence "Direct link to Tips for Getting the Most Out of Markdown in Confluence") **Start with new pages.** Rather than converting your existing documentation immediately, begin by writing new pages in Markdown. This lets your team get comfortable with the editing workflow before touching existing content. **Use the WYSIWYG mode as a crutch.** If you forget a specific Markdown syntax, switch to the WYSIWYG mode in the editor toolbar. Format the content visually, then switch back to Markdown mode to see the generated syntax. This is an excellent way to learn Markdown incrementally. **Specify language identifiers on code blocks.** Always add a language tag after the opening triple backticks (for example, `python`, `javascript`, `sql`). This ensures syntax highlighting is applied correctly and makes your code snippets more readable for the team. **Leverage PlantUML for diagrams.** Instead of uploading image files for architecture diagrams, flowcharts, and sequence diagrams, write them in PlantUML syntax directly in your Markdown content. They render automatically and can be updated by editing the text -- no image editor required. **Take advantage of merged cells for complex tables.** Standard Markdown tables are limited to simple grids. Enhanced Markdown for Confluence supports merged cells, which means you can build the kind of complex status tables and comparison matrices that project management and technical documentation often require. **Test your exports.** Although Enhanced Markdown for Confluence renders to standard Confluence storage format (meaning PDF, HTML, and Word exports work out of the box), always verify the export output for pages with complex formatting. Nested tables, PlantUML diagrams, and color syntax elements should be checked in your most commonly used export format. *** ## Related Resources[​](#related-resources "Direct link to Related Resources") * [Enhanced Markdown for Confluence usage guide](/apps/enhanced-markdown-for-confluence.md) -- complete documentation for all features, configuration, and tips * [Confluence Markdown vs WYSIWYG: Which Should You Use?](/blog/faq-confluence-markdown-vs-wysiwyg.md) -- detailed comparison of Markdown and WYSIWYG editing approaches in Confluence * [Best Confluence Apps for Developers](/blog/best-confluence-apps-developers.md) -- roundup of NGPILOT apps that make Confluence a better development workspace * [How to add a block quote in Confluence](/blog/block-quote-confluence.md) -- three methods compared: native indent, Markdown `>` syntax, and the Quote macro * [Advanced Code Blocks in Confluence](/blog/advanced-code-blocks-confluence.md) -- how-to guide for advanced code display features including line numbers, code folding, and Monaco editor integration 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) 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:** * [faq](/blog/tags/faq.md) * [confluence](/blog/tags/confluence.md) * [markdown](/blog/tags/markdown.md) * [markdown-editor](/blog/tags/markdown-editor.md) * [writing](/blog/tags/writing.md)