marklas 0.1.1

Bidirectional converter between GitHub Flavored Markdown and Atlassian Document Format

Marklas

Markdown ⇄ AST ⇄ ADF

Installation

pip install marklas

Usage

Markdown → ADF

from marklas.parser.md import parse
from marklas.renderer.adf import render

doc = parse("**Hello** world")
adf = render(doc)

# {
#   "type": "doc",
#   "version": 1,
#   "content": [
#     {
#       "type": "paragraph",
#       "content": [
#         {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
#         {"type": "text", "text": " world"}
#       ]
#     }
#   ]
# }

ADF → Markdown

from typing import Any

from marklas.parser.adf import parse
from marklas.renderer.md import render

adf: dict[str, Any] = {
    "type": "doc",
    "version": 1,
    "content": [
        {
            "type": "paragraph",
            "content": [
                {"type": "text", "text": "Hello", "marks": [{"type": "strong"}]},
                {"type": "text", "text": " world"},
            ],
        }
    ],
}
doc = parse(adf)
md = render(doc)

# "**Hello** world\n"

Conversion Rules

Block

ADF	AST	Markdown
paragraph	Paragraph(children)	inline content
heading (level 1-6)	Heading(level, children)	# ~ ######
codeBlock (language?)	CodeBlock(code, language?)	```lang\ncode\n```
blockquote	BlockQuote(children)	> text
bulletList > listItem	BulletList(items) > ListItem(children)	- item
orderedList > listItem	OrderedList(items, start) > ListItem(children)	1. item
taskList > taskItem	BulletList > ListItem(checked=bool)	- [x] / - [ ]
decisionList > decisionItem	BulletList > ListItem(checked=bool)	- [x] / - [ ]
rule	ThematicBreak	---
table > tableRow > tableHeader/tableCell	Table(head, body, alignments)	GFM table
mediaSingle > media (external)	Paragraph > Image(url, alt)	
mediaSingle > media (non-external)	Paragraph > Text("[Image: id]")	[Image: id]
mediaGroup > media	Paragraph > Image/Text	 / [Image: id]
panel	BlockQuote(children)	> text
expand / nestedExpand (title?)	BlockQuote(children) (title prepended)	> title\n> text
layoutSection > layoutColumn	flattened blocks	columns flattened
blockCard (url)	Paragraph > Link(url)	[url](url)
embedCard (url)	Paragraph > Link(url)	[url](url)

Inline

ADF	AST	Markdown
text	Text(text)	plain text
text + strong mark	Strong(children)	**text**
text + em mark	Emphasis(children)	*text*
text + strike mark	Strikethrough(children)	~~text~~
text + code mark	CodeSpan(code)	`code`
text + link mark	Link(url, children, title?)	[text](url)
hardBreak	HardBreak	\ + newline
—	SoftBreak	newline
mention	CodeSpan(code)	`@user`
emoji	Text(text)	:shortName:
date	CodeSpan(code)	`2024-01-01`
status	CodeSpan(code)	`status text`
inlineCard (url)	Link(url)	[url](url)
—	Image(url, alt, title?)	

Not Supported

Element	Behavior
ADF marks: underline, textColor, backgroundColor, subsup	silently ignored
ADF blocks: extension, bodiedExtension, syncBlock, bodiedSyncBlock	[type] placeholder
ADF inlines: placeholder, inlineExtension, mediaInline	[type] placeholder
ADF table: colspan, rowspan	expanded with empty cells
ADF table: background, colwidth	attributes ignored
ADF table: non-paragraph cell content	[type] placeholder
Markdown: raw HTML (block, inline)	silently ignored

Development

uv sync --extra dev
uv run pytest -v
uv run black src/ tests/