Confluence Markdown: How to Paste, Import & Macro

1. Understanding the Confluence Editor Architecture

Confluence relies on an internal XML storage format (Confluence XHTML) to manage wiki page nodes. Historically, this architectural decision meant that writing or importing plain text documents like Markdown was not supported natively. To display structured content, users had to use visual rich-text controls or purchase third-party formatting add-ons.

With the introduction of Confluence Cloud, Atlassian refactored its editing engine. The modern cloud editor runs a real-time converter that intercepts keyboard inputs and clipboard pastes, translating standard Markdown syntax into Confluence storage blocks. This setup allows technical writers to reuse their existing Markdown documentation files directly inside Confluence without manual formatting.

However, this conversion is a one-way process. Once Markdown is pasted or typed into the visual editor, it is converted into Confluence's internal storage format. The raw markdown formatting is lost unless you use the Markdown Macro, which preserves the plain-text syntax for future edits.

Understanding this layout translation process is necessary for teams trying to coordinate documentation workflows. When a writer pastes markdown into the editor, the browser intercepts the text copy and parses the elements. It resolves the headers, list sequences, and code blocks, generating the corresponding XHTML elements. This process makes the document look correct but removes the original text codes. If a developer edits the text later, they must use visual controls rather than editing markdown characters.

2. Real-time Editor Shortcuts

When writing inline, you can use markdown in Confluence by typing standard formatting characters directly in the editor pane. The software parses them instantly.

When you type these shortcuts, the visual editor updates the text block immediately. For example, typing a hash character followed by a space changes the line to a Heading 1 layout. If you want to undo this conversion and display raw characters, press Ctrl + Z (or Cmd + Z on macOS).

These shortcuts save time when drafting notes directly in Confluence. They allow writers who are familiar with Markdown to use the same habits without needing to interact with visual formatting menus. However, lists and headers can sometimes be triggered by accident. For instance, typing a hyphen at the start of a list option or logging a key with a hash marker can trigger a conversion. Pressing undo resolves these accidental triggers.

3. Pasting Markdown & Markup Macros

If you have structured markdown files (like READMEs), you can copy the raw text and paste it into Confluence. The editor parses standard headers, list loops, links, and tables.

If you want to preserve the raw markdown formatting block for future edits, use the **Markdown Macro**:

1. Edit your Confluence page, and click the "+" icon in the top toolbar.
2. Search for "Markup" or "Markdown".
3. Select the macro widget and choose "Markdown" in the format options dropdown.
4. Paste your raw markdown code in the text field and click Insert.

Using the Markdown Macro keeps your plain text source syntax editable. This is useful for development teams who maintain a single source of truth for documentation in their code repository and need to copy changes to Confluence regularly.

When pasting markdown directly, the Confluence cloud editor handles list conversions, formatting codes, and headers. However, if the text contains complex Markdown layout structures (such as nested code blocks within list items), the direct paste can fail, resulting in unformatted text logs.

Another benefit of using the Markdown macro is that it isolates the markdown logic from the rest of the Confluence document structure. This isolation prevents other users from accidentally breaking your document format when editing other parts of the wiki page. It also ensures that the markdown renders correctly across different themes.

4. Code Blocks in Confluence

Confluence includes a dedicated **Code Block macro** to display source code. It features line numbers, syntax highlighting themes, and a copy button:

• To create a code block using shortcuts, type three backticks (```) followed by a space in the editor window. Confluence will insert the Code Block macro placeholder.
• You can configure the language settings inside the macro options bar to enable syntax highlighting for JavaScript, Python, CSS, HTML, and other languages.
• The macro settings allow you to choose visual themes, display line numbers, and set the block to collapsible to save vertical space on long pages.

If you paste raw code containing backticks directly, Confluence can mistake them for inline code triggers. Using the slash command `/code` to open the macro dialog before pasting code snippets helps prevent this formatting issue.

The Code Block macro is a core element for software engineering documentation. It isolates the code text from the visual formatting engine. This isolation prevents issues like auto-correcting quotes or matching double dashes, which can break code syntax. It also allows visitors to copy the code block to their clipboard with a single click.

5. Advanced API Publishing & Automation

For engineering groups, manually copy-pasting markdown documents is not a practical solution. Instead, teams often automate publishing tasks. You can send markdown text directly to Confluence's REST API.

When publishing through the REST API, you specify the target layout block using Confluence XHTML storage format. To convert markdown to XHTML, you can run tools like Pandoc or markdown-it during your CI/CD build pipelines. This conversion step compiles markdown files into styled HTML snippets before sending them in the API request body.

Using this workflow, teams can host documentation in their git repositories. When changes are merged, the automation parses the markdown, compiles it to XHTML, and updates the Confluence wiki page automatically. This setup guarantees that both the repository and the wiki stay in sync.

6. Formatting Pitfalls and Troubleshooting

When writing markdown inside Confluence, keep these common formatting challenges in mind:

• Line Spacing Requirements: The Confluence markdown converter requires blank lines between different blocks. For example, if you place a list directly under a heading without a blank line, the formatting can fail.
• Legacy Server Environments: Self-hosted Confluence Server (on-premises) instances use an older editing engine. They do not support modern markdown copy-pasting or shortcuts. For these environments, you must use the standard Markup macro or third-party add-ons.
• One-Way Conversion: Remember that pasting markdown directly into a modern page converts it into Confluence's internal storage layout. If you export the page back to text later, the original markdown syntax is lost. Use the Markdown Macro if you need to keep the raw text editable.
• Unsupported Elements: Confluence does not support raw HTML tags, footnote links, or image sizing attributes inside markdown text blocks. These elements will render as plain text characters.

For large documentation projects, we recommend formatting files in a local editor before pasting them into Confluence. This approach ensures consistent spacing and structure across your pages.

Also, the visual editor's real-time parser can conflict with markdown syntax if you type quickly. For instance, if you type double asterisks followed by a space and then type text, the parser can fail to recognize the bold block. To fix this, select the text manually and use the visual bold button or type the symbols carefully.