marklas 0.6.0

Bidirectional converter between GitHub Flavored Markdown and Atlassian Document Format

Marklas

Bidirectional converter between Markdown and Atlassian Document Format (ADF).

한국어 · 日本語

---

Why Marklas?

Confluence and Jira store documents in ADF — a verbose JSON structure. Marklas converts it to readable Markdown and back through a union AST:

Markdown ⇄ Union AST ⇄ ADF

ADF-only features (panels, mentions, colored text, etc.) are preserved as HTML elements with adf attributes, so the full structure survives a roundtrip:

<aside adf="panel" params='{"panelType":"info"}'>

This is an info panel — readable as plain Markdown.

</aside>

User <span adf="mention" params='{"id":"abc123"}'>@John</span> approved this.

Pass plain=True to strip roundtrip metadata and get clean Markdown for LLM consumption.

Installation

pip install marklas

Usage

from marklas import to_adf, to_md

# Markdown → ADF
adf = to_adf("## Hello\n\nThis is **bold**.")

# ADF → Markdown (with roundtrip metadata)
md = to_md(adf_document)

# ADF → Markdown (clean, no metadata)
plain_md = to_md(adf_document, plain=True)

# Roundtrip
original_adf = fetch_confluence_page()
markdown = to_md(original_adf)          # edit in any Markdown editor
restored_adf = to_adf(markdown)         # push back — structure preserved

Token Efficiency

Markdown is significantly more compact than ADF JSON — critical for LLM-based workflows where every token counts.

	ADF JSON	Markdown	Markdown (plain)
Tokens	243,217	76,332	47,794
Reduction	—	3.2x	5.1x

Measured on 7 real Confluence pages (pretty-printed JSON) using GPT-4o tokenizer (tiktoken).

Documentation

• Mapping Reference — how each ADF node maps to Markdown
• LLM Editing Guide — guide for LLMs editing marklas output

Development

uv sync --extra dev
uv run pytest -v