md2conf (markdown-to-confluence)

The markdown-to-confluence package automates the synchronization of Markdown documentation from VCS (like GitHub/GitLab) to Confluence wiki. It parses Markdown, converts it to Confluence Storage Format (XHTML), and uses the Confluence REST API v2 to upload content and images.

Supported Markdown elements include:

• Sections, subsections, and Table of Contents
• Text formatting: bold, italic, monospace, <ins>underline</ins>, strikethrough, subscript, and superscript
• Lists (ordered/unordered), block quotes, and task lists
• Links (internal section links and external URLs)
• Tables, footnotes, and emojis
• Code blocks (Python, JSON, XML, etc.)
• Admonitions and alert boxes (GitHub/GitLab style)
• Collapsed sections
• Diagrams: draw.io, Mermaid, and PlantUML
• Math formulas (LaTeX notation)
• Confluence-specific elements: status labels and date widgets

When publishing a new page, md2conf derives the Confluence title using the following priority:

1. Front-matter: The title attribute in a YAML or JSON block at the top of the file.
2. Topmost unique heading: The text of the first # heading, provided there is only one such heading in the document.
3. File name: The filename (minus .md) combined with a digest to ensure uniqueness.

If the title in the front-matter or the unique heading changes, the Confluence page title is updated automatically.

---
title: My Custom Page Title
---

# This would be used if front-matter title is missing

When synchronizing Markdown to Confluence, you must decide how to handle existing inline comments on the Confluence page. This is controlled by the comments configuration option.

Available Strategies:

• Remove: Transition all existing inline comments to the resolved state when the Markdown source is updated.
• Check for open: Skip synchronizing the page entirely if any unresolved inline comments are found.
• Keep: Attempt to merge comments added in Confluence with the new content generated from Markdown (uses a heuristic match).

Technical Note: To inspect inline comments, you must use a connection with the read:comment:confluence scope.

When synchronizing Markdown to Confluence, md2conf attempts to preserve existing Confluence comments using a three-step matching process:

1. Word-level matching: Uses a difflib.SequenceMatcher to pair paragraphs in Confluence with their best match in the new Markdown output. This allows for paragraph insertions, deletions, or moves.
2. Character-level matching: Identifies unchanged blocks of text within paragraphs to allow comment transfer even if a paragraph has been partially edited.
3. Merge algorithm: Inserts the identified inline comments into the generated XML tree.

Note: If a Confluence comment cannot be mapped to the updated Markdown content, a warning is emitted and the comment is marked as resolved.

If a Markdown link points to a file within the directory hierarchy being synchronized, md2conf will automatically upload that file as an attachment to the corresponding Confluence page.

Supported file types include:

• PDFs (*.pdf)
• Word documents (*.docx)
• Spreadsheets (*.xlsx)
• Plain text (*.txt)
• Logs (*.log)

The MIME type is automatically determined based on the file extension.

You can create structured macro panels in Confluence using reStructuredText (rST) style admonition syntax. The format follows !!! <type> "<optional title>" followed by the content on indented lines.

Supported types include:

• !!! info (with or without an explicit title)
• !!! tip
• !!! note
• !!! warning
• !!! attention
• !!! caution
• !!! danger
• !!! error
• !!! hint
• !!! important
• !!! question
• !!! quote
• !!! success
• !!! abstract
• !!! bug
• !!! example
• !!! failure

!!! info "Optional explicit title"
    This is an information panel with an explicit title.

    This is the second paragraph with a [link](https://example.com/).

!!! tip "Tip of the day"
    This is a structured macro panel showing a tip.

Since Markdown lacks a native syntax for Confluence header columns (cells with darker backgrounds), md2conf uses a convention: if a Markdown table has a blank column immediately following the first column, the first column is treated as a header column. The separator column is automatically omitted in the Confluence output.

| Number | | English | Hungarian |
| ------ |-| ------- | --------- |
| 1      | | one     | egy       |
| 2      | | two     | kettő     |
| 3      | | three   | három     |

You can link a Markdown file to a Confluence page using two methods:

1. Explicit Association

Specify the exact Confluence page ID using a Markdown comment anywhere in the file. This is the most reliable method for existing pages.

2. Implicit Association

md2conf automatically pairs Markdown files with Confluence pages if they share the same title.

• If the page doesn't exist, it is created automatically.
• If the page exists, md2conf only synchronizes it if the page is part of a 'trusted' hierarchy (e.g., it traces back to a root page specified via CLI or an index.md/README.md file in the directory structure).

Overriding Space Keys

You can override the default space (set via env vars or CLI) on a per-document basis using a Markdown comment.

<!-- confluence-page-id: 20250001023 -->

<!-- confluence-space-key: SPACE -->

By default, md2conf uses Confluence REST API v2, which is recommended for Confluence Cloud.

If you are using an older Data Center or Server installation that only supports REST API v1, you must explicitly set the API version using the --api-version=v1 flag or the CONFLUENCE_API_VERSION environment variable.

You can create Confluence user mentions using a specific Markdown link syntax. md2conf scans documents, extracts these links, and attempts to match them to Confluence users using Confluence Query Language (CQL) based on the name, then verifies via email.

Syntax: [Name](mailto:email@example.com)

Example:

[Levente Hunyadi](mailto:levente.hunyadi@example.com)

Note: If the lookup fails (e.g., due to private email settings or no matching display name), the link remains a standard Markdown link.

If you do not want md2conf to communicate directly with the Confluence REST API, you can use local output mode. In this mode, the tool reads Markdown files (or a directory) and writes Confluence Storage Format (*.csf) files.

Confluence Storage Format is an XHTML derivative containing Confluence-specific tags for elements like images, code blocks, and info panels. You can manually push these generated .csf files to Confluence using the API (e.g., via curl).