Skip to main content

Confluence Markdown Editor FAQ: Syntax, Tables & Code Blocks

· 12 min read
NGPilot
NGPilot
NGPilot

Confluence is one of the most widely used knowledge management platforms in the enterprise world, but its built-in editor is strictly WYSIWYG. For developers, technical writers, and content teams who already live in Markdown -- writing README files, documentation repos, pull request descriptions, and API references in plain text -- the absence of native Markdown support in Confluence is a daily frustration. You end up copying content from your Markdown files and manually reformatting it through toolbar buttons and dialog boxes, losing time and introducing inconsistencies along the way.

Enhanced Markdown for Confluence by NGPILOT solves this problem by embedding a full Markdown editor directly inside Confluence. You write in the same Markdown syntax you use everywhere else, and the app renders it to standard Confluence storage format. The result looks and behaves like any other Confluence page, but the authoring experience is entirely Markdown-based. This FAQ answers the questions teams ask most often about writing Markdown in Confluence with this app, covering syntax support, code blocks, tables, images, exporting, and how the Markdown editing experience compares to Confluence's native editor.

Frequently Asked Questions​

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, powered by Toast UI Editor with both a raw Markdown mode and a WYSIWYG mode you can switch between.

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?​

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 both a raw Markdown mode and a WYSIWYG mode powered by Toast UI Editor, so you can switch between them depending on your preference.
  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.

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 (>)
  • 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?​

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.

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?​

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 Markdown editor also provides a WYSIWYG mode powered by Toast UI Editor, so you can switch to a visual editing experience when needed without leaving the macro.

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.

FeatureEnhanced MarkdownNative WYSIWYG
Editing modeRaw Markdown + WYSIWYGWYSIWYG only
Keyboard-centric writingYesPartial (shortcuts)
Live previewYes — switch to WYSIWYG modeNative (inline)
Code syntax highlightingFenced blocks with language tagsCode block macro
Table merged cellsSupportedSupported
PlantUML diagramsSupportedRequires separate macro
Dark mode adaptationAutomaticAutomatic
Content portabilityPlain text, works everywhereConfluence storage format only
Version control diffsClean, line-by-lineXML, hard to review
Full macro libraryCommon macros supportedAll macros available
Re-editing sourceSource preservedN/A (visual)

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.

ElementSyntaxExample
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 list1. item1. 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 blockTriple backticks + languageSee code block examples above
Blockquote> text> This is a note
Horizontal rule------
TablePipe syntax with header rowSee table examples above

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.