marklas 0.2.1

Bidirectional converter between GitHub Flavored Markdown and Atlassian Document Format

Marklas

Markdown ⇄ ADF

Installation

pip install marklas

Usage

Markdown → ADF

from marklas import to_adf

adf = to_adf("**Hello** world")

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

ADF → Markdown

from marklas import to_md

md = to_md(adf)

# "**Hello** world\n"

Conversion Rules

Block

ADF	Markdown
paragraph	inline content
heading (level 1-6)	# ~ ######
codeBlock (language?)	```lang\ncode\n```
blockquote	> text
bulletList > listItem	- item
orderedList > listItem	1. item
taskList > taskItem	- [x] / - [ ]
decisionList > decisionItem	- [x] / - [ ]
rule	---
table > tableRow > tableHeader/tableCell	GFM table (merged cells are split, only paragraph content)
mediaSingle > media (external)	
mediaSingle > media (non-external)	[Image: id]
mediaGroup > media	 / [Image: id]
panel	> text
expand / nestedExpand (title?)	> title\n> text
layoutSection > layoutColumn	columns flattened
blockCard (url)	[url](url)
embedCard (url)	[url](url)

Inline

ADF	Markdown
text	plain text
text + strong mark	**text**
text + em mark	*text*
text + strike mark	~~text~~
text + code mark	`code`
text + link mark	[text](url)
hardBreak	\ + newline
mention	`@user`
emoji	:shortName:
date	`2024-01-01`
status	`status text`
inlineCard (url)	[url](url)

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
Markdown: raw HTML (block, inline)	silently ignored

Development

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