marklassian-py

A lightweight Python library that converts Markdown to the Atlassian Document Format (ADF). Built for easy integration with Atlassian products like Jira and Confluence.

This is a Python port of the excellent marklassian JavaScript library by @jamsinclair.

Features

• Convert Markdown to ADF with a single function call
• Support for common Markdown syntax including GFM task lists
• Minimal dependencies (only mistune)
• Full type hints for IDE support
• Python 3.10+

Installation

pip install marklassian

Or with uv:

uv add marklassian

Usage

from marklassian import markdown_to_adf

markdown = "# Hello World\n\nThis is **bold** and *italic* text."
adf = markdown_to_adf(markdown)

The result is a dictionary that can be serialized to JSON:

import json
print(json.dumps(adf, indent=2))

Supported Markdown Features

• Headings (H1-H6)
• Paragraphs and line breaks
• Emphasis (bold, italic, strikethrough)
• Links and images
• Inline code and code blocks with language support
• Ordered and unordered lists with nesting
• Blockquotes
• Horizontal rules
• Tables
• Task lists (GitHub Flavored Markdown)

API Reference

markdown_to_adf(markdown: str, *, jira_mentions: bool = False) -> AdfDocument

Converts a Markdown string to an ADF document object.

Types

class AdfMark(TypedDict, total=False):
    type: Required[str]
    attrs: dict[str, Any]

class AdfNode(TypedDict, total=False):
    type: Required[str]
    attrs: dict[str, Any]
    content: list[AdfNode]
    marks: list[AdfMark]
    text: str

class AdfDocument(TypedDict):
    version: Literal[1]
    type: Literal["doc"]
    content: list[AdfNode]

Jira account mentions

Pass jira_mentions=True to convert Jira wiki mentions into ADF mention nodes:

markdown_to_adf("Hi [~accountId:557057:user-id]", jira_mentions=True)

This option is disabled by default. Code and escaped mention syntax remain unchanged.

Caveats

This library aims to provide a lightweight and mostly accurate conversion from Markdown to ADF.

For complex Markdown documents or strict ADF conformance requirements, consider using the official Atlassian libraries. Note that those are heavier dependencies.

References

• Atlassian Document Format Reference
• ADF Interactive Builder
• Original marklassian (JavaScript)

Credits

This library is a Python port of marklassian by Jamie Sinclair. All credit for the original implementation and conversion logic goes to them.

License

MIT - see LICENSE for details.