marklas 0.5.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 invisible HTML comment annotations, so the full structure survives a roundtrip:

<!-- adf:panel {"panelType": "info"} -->
This is an info panel — readable as plain Markdown.
<!-- /adf:panel -->

User <!-- adf:mention {"id": "abc123", "text": "@John"} -->`@John`<!-- /adf:mention --> approved this.

Pass annotate=False to strip annotations and get clean Markdown.

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 annotations for lossless roundtrip)
md = to_md(adf_document)

# ADF → Markdown (clean, no annotations)
clean_md = to_md(adf_document, annotate=False)

# 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 (annotated)	Markdown (plain)
Tokens	243,217	76,541	41,744
Reduction	—	3.2x	5.8x

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

Documentation

• ADF ↔ Markdown Mapping Reference — how each ADF node maps to Markdown
• LLM Editing Guide — rules for LLMs/MCP servers editing marklas output

Note: Table cells use inline HTML (<ul>, <code>, <br>) for block-level content. Raw HTML and other Markdown-only constructs are dropped during ADF conversion. See the mapping reference for details.

Development

uv sync --extra dev
uv run pytest -v