Skip to content

Markdown Syntax Guide

This document describes the standard and special markdown syntax supported by the md_to_conf converter. The converter transforms markdown files into Confluence-compatible HTML using the Python markdown library with additional custom processing.

Table of Contents

Standard Markdown Support

The converter supports all standard markdown syntax through the Python markdown library with the following extensions enabled:

Headers

# Header 1
## Header 2  
### Header 3
#### Header 4
##### Header 5
###### Header 6

Headers are converted to Confluence headings and can be used as anchor targets for internal links.

Text Formatting

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

Lists

Unordered Lists

* Item 1
* Item 2
  * Nested item 2.1
  * Nested item 2.2
* Item 3

Ordered Lists

1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

The converter uses the mdx_truly_sane_lists extension for proper nested list handling.

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Tables are supported through the tables extension and converted to Confluence table format.

[Link text](https://example.com)
[Link with title](https://example.com "Title")

Blockquotes

> This is a blockquote
> 
> Multiple lines are supported

See Special Confluence Features for enhanced blockquote functionality.

Special Confluence Features

Enhanced Blockquotes with Status Panels

The converter automatically detects special blockquote patterns and converts them to Confluence status panels:

Info Panel (Blue Icon)

> This is general information.

Warning Panel (Yellow Caution Icon)

> Warning: This is a warning message.

Success Panel (Green Check Icon)

> Success: This is a success message.

Error Panel (Red Cross Icon)

> Error: This is an error message.

Note Panel (Special ADF Format)

> Note: This is a note.

Note: The type detection is case-insensitive and supports various formats like "Warning:", "Warning :", etc.

GitHub-Flavored Markdown Alerts

The converter supports GitHub-flavored markdown alert syntax, which takes precedence over traditional blockquote processing. These alerts provide a standardized way to create different types of callout panels.

Supported Alert Types

NOTE Alert

> [!NOTE]
> Useful information that users should know, even when skimming content.

Converts to a Confluence info panel (blue icon).

TIP Alert

> [!TIP]
> Helpful advice for doing things better or more easily.

Converts to a Confluence tip panel (green icon).

IMPORTANT Alert

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

Converts to a special Confluence ADF panel with note styling.

WARNING Alert

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

Converts to a Confluence note panel (yellow caution icon).

CAUTION Alert

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Converts to a Confluence warning panel (red cross icon).

Features

  • Case Insensitive: Works with [!note], [!NOTE], [!Note], etc.
  • Multi-line Support: Supports multiple paragraphs within alerts
  • HTML Formatting: Preserves bold, italic, and other formatting inside alerts
  • Precedence: GitHub alerts are processed before traditional blockquote patterns
  • Single Line: Content can be on the same line as the alert type

Examples

Single Line Alert

> [!WARNING] This is a single-line warning message.

Multi-line Alert

> [!IMPORTANT]
> This is the first paragraph of an important message.
>
> This is a second paragraph with **bold** and *italic* formatting.

Mixed Content

> [!TIP]
> Here's a helpful tip with a code example:
>
> ```bash
> npm install package-name
> ```

Custom Panel Syntax

For more explicit control over panel types, use the custom tilde syntax:

Info Panel

~?This is an info panel.?~

Warning Panel

~%This is a warning panel.%~

Success Panel

~^This is a success panel.^~

Error Panel

~$This is an error panel.$~

Note Panel

~!This is a note panel.!~

Table of Contents Generation

Simple TOC

[TOC]

This creates a basic table of contents macro in Confluence.

DocToc Integration

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

The converter automatically replaces doctoc-generated sections with Confluence TOC macros with advanced parameters: - Printable: true - Style: disc - Max Level: 7 - Min Level: 1 - Type: list - Outline: clear

Contents Addition

When using the --add-contents option, a comprehensive table of contents is automatically added to the beginning of the page with these parameters: - Printable: true - Style: disc - Max Level: 5 - Min Level: 1 - Class: rm-contents - Type: list - Outline: false

Code Blocks

Fenced Code Blocks

```javascript
function example() {
    return "Hello, World!";
}
```

Code Block without Language

```
This is a generic code block
```

Features: - All code blocks are converted to Confluence code macros - Theme: Midnight (dark theme) - Line numbers: enabled - Language detection from fence language specification - Falls back to "none" if no language specified - HTML entities are properly unescaped

Supported Languages: Any language supported by Confluence code macros (JavaScript, Python, Java, SQL, etc.)

Mermaid Diagrams

When --mermaid is passed on the command line, fenced code blocks tagged mermaid are rendered to PNG images and uploaded as page attachments before the page is published.

Syntax

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do it]
    B -->|No| D[Skip it]
```

Supported Diagram Types

All Mermaid diagram types are supported, including:

  • Flowcharts (graph TD, flowchart LR, …)
  • Sequence diagrams (sequenceDiagram)
  • Class diagrams (classDiagram)
  • State diagrams (stateDiagram-v2)
  • Entity-Relationship diagrams (erDiagram)
  • Gantt charts (gantt)
  • Pie charts (pie)
  • Git graphs (gitGraph)

Rendering Strategies

Rendering is attempted in this order:

  1. Local mmdc CLI — Used when mmdc (@mermaid-js/mermaid-cli) is on PATH. No network required, best quality.
  2. mermaid.ink public API — Automatic fallback when mmdc is unavailable. Requires outbound HTTPS.

If rendering fails, the original fenced code block is preserved and a warning is logged.

Notes

  • HTML entities (e.g. &amp;, &gt;) in the code block are decoded before being sent to the renderer.
  • Each diagram is numbered sequentially: mermaid_1.png, mermaid_2.png, …
  • Generated images are uploaded as Confluence page attachments alongside any other images.

When multiple Markdown files are published in a single md-to-conf invocation, relative links between those files are automatically rewritten to the corresponding Confluence page URLs.

Syntax

Standard Markdown relative links:

[Guide](guide.md)
[API Reference](reference.md#api-section)
[Sibling doc](../other/page.md)

Resolution Rules

  • The link target is resolved relative to the directory of the file containing the link.
  • If the resolved path matches one of the files being published, the link is rewritten to the Confluence page URL.
  • Fragment anchors (#section) are preserved and appended to the Confluence URL.
  • Links pointing to files not in the current publish batch are left unchanged.

Example

Given three files published together:

md-to-conf "docs/*.md" TST -a "My Docs"

A link in docs/intro.md:

See the [Architecture Overview](architecture.md#components) for details.

Becomes (after publishing):

<a href="https://example.atlassian.net/wiki/spaces/TST/pages/42/Architecture+Overview#components">Architecture Overview</a>

HTML Comments

<!-- This is a hidden comment -->

HTML comments are converted to Confluence placeholder macros (<ac:placeholder>) which render as hidden comments in Confluence.

References and Footnotes

Footnote References

Here is some text with a footnote reference[^1].

[^1]: This is the footnote content with a [link](https://example.com).

Features: - Footnotes are supported through the footnotes extension - References are converted to superscript links - Footnote content is processed and linked appropriately

[Link to section](#header-name)

Features: - Links to headers within the same page are automatically converted - Supports both default and bitbucket markdown source formats - Different anchor prefixes based on source: - Default: # - Bitbucket: #markdown-header- - Proper URL encoding for Confluence page URLs - Different output formats for editor versions 1 and 2

Supported Markdown Sources

Default Format

[Link to header](#my-header)

Bitbucket Format

[Link to header](#markdown-header-my-header)

Images and Attachments

Image Syntax

![Alt text](path/to/image.png)
![Alt text with title](path/to/image.png "Image title")

Features: - Local images are automatically uploaded as Confluence attachments - Image paths are converted to Confluence attachment URLs - HTTP/HTTPS URLs are left unchanged - Alt text is preserved in the attachment metadata

Automatic Processing: - Local file paths are resolved relative to the markdown file location - Images are uploaded to the target Confluence page - Image references are updated to point to Confluence attachment URLs - Format: /wiki/download/attachments/{page_id}/{filename} or /download/attachments/{page_id}/{filename}

Emoji Support

Emoji Removal

When using the --remove-emojies option, the converter removes Unicode emoji characters:

Removed Emoji Ranges: - Emoticons: \U0001F600-\U0001F64F - Symbols & Pictographs: \U0001F300-\U0001F5FF
- Transport & Map Symbols: \U0001F680-\U0001F6FF - Flags (iOS): \U0001F1E0-\U0001F1FF

Example:

This text has emojis 😀 🎉 🚀 🇺🇸

With --remove-emojies, becomes:

This text has emojis

Advanced Features

Command Line Options

The converter supports several command-line options that affect markdown processing:

Content Options

  • --contents / -c: Generate a comprehensive table of contents at the beginning of the page
  • --title: Set a custom page title (otherwise uses first line of markdown file)
  • --remove-emojies: Remove all Unicode emojis from the content
  • --mermaid: Render mermaid fenced code blocks as PNG images before uploading. Uses local mmdc CLI if available, otherwise falls back to the mermaid.ink public API.
  • --exclude PATTERN: Exclude files matching a glob pattern from publishing. Can be specified multiple times. Inline !-prefixed entries in the file list are equivalent.

Markdown Source Format

  • --markdownsrc / -mds: Specify markdown source format
  • default: Standard markdown anchor format (#header-name)
  • bitbucket: Bitbucket-style anchors (#markdown-header-header-name)

Page Management

  • --label: Add labels to the Confluence page (can be used multiple times)
  • --property: Set content properties on the page (format: key=value, can be used multiple times)
  • --attachment / -t: Upload file attachments to the page (paths relative to markdown file)

Processing Options

  • --version / -v: Confluence editor version (1 or 2, default: 2)
  • --simulate / -s: Show conversion result without uploading to Confluence
  • --delete / -d: Delete the page instead of creating/updating it

Editor Version Support

The converter supports two editor versions with different output formats:

Editor Version 1 (Legacy)

  • Uses Confluence-specific XML link format
  • Internal links: <ac:link ac:anchor="..."><ac:plain-text-link-body><![CDATA[...]]></ac:plain-text-link-body></ac:link>

Editor Version 2 (Modern)

  • Uses standard HTML anchor links
  • Internal links: <a href="...#..." title="...">...</a>
  • Full Confluence page URLs with anchor fragments

Markdown Source Formats

Default Source

  • Standard markdown anchor format: #header-name
  • Postfix pattern for duplicates: _%d

Bitbucket Source

  • Bitbucket-style anchors: #markdown-header-header-name
  • Postfix pattern for duplicates: _%d

Processing Order

The converter processes markdown in this order: 1. Convert markdown to HTML using Python markdown library 2. Remove title if not explicitly provided 3. Process table of contents markers 4. Convert info/warning/success/error macros 5. Convert HTML comments to placeholders 6. Render Mermaid diagrams to images (if --mermaid is set) 7. Convert code blocks to Confluence macros 8. Remove emojis (if requested) 9. Add contents section (if requested) 10. Process footnote references 11. Process internal anchor links 12. Rewrite cross-document links (if multiple files are being published)

Limitations and Notes

  1. Cross-Page Links (single-file mode): When publishing a single file, links to other .md files are not rewritten. Publish files together in one invocation to enable automatic cross-document link resolution.

  2. Image Processing: Only local images are uploaded as attachments. External URLs are preserved as-is.

  3. Code Language Detection: Language detection relies on the fence specification. Unknown languages default to "none".

  4. Panel Type Detection: Blockquote panel type detection is case-insensitive but requires specific keywords (Warning, Success, Error, Note).

  5. Anchor Generation: Anchor names are automatically generated from header text with special character removal and space-to-dash conversion.

  6. Nested Lists: Proper indentation is required for nested list items (2+ spaces for sub-items).

  7. Emoji Removal: When enabled, removes all emojis indiscriminately - cannot selectively preserve certain emojis.

  8. Mermaid Rendering: Requires either mmdc on PATH or outbound HTTPS access to mermaid.ink. If neither is available, the original fenced block is preserved.

Examples

For complete examples, see the test files: - tests/testfiles/basic.md - Basic markdown features - tests/testfiles/advanced.md - Advanced features including panels, nested lists, and internal links