marklas 0.7.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:

Markdown ⇄ 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

Advanced Usage

For pipelines that need to modify the AST between parsing and rendering — such as uploading local images as Confluence attachments — use Transformer:

from marklas import Transformer, parse_md, render_adf
from marklas.ast import Media

t = Transformer()

@t.register(Media)
def _(node: Media) -> Media | None:
    if node.type == "external":
        uploaded = upload_attachment(page_id, node.url)
        return Media(type="file", id=uploaded.media_id, collection=uploaded.collection)
    return None

doc = parse_md(markdown)
new_doc = t(doc)
adf = render_adf(new_doc)

Function	Description
parse_md(md)	Markdown → AST
parse_adf(adf)	ADF JSON → AST
render_md(doc)	AST → Markdown
render_adf(doc)	AST → ADF JSON
Transformer	Registry of typed visitors for AST rewriting

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