marklas 0.4.4

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 rich JSON structure with panels, layouts, mentions, colored text, and more. Standard Markdown can only represent a subset of these features.

Marklas defines a union AST that covers both specs, then converts in both directions through it:

Markdown ⇄ Union AST ⇄ ADF

Nodes shared by both formats (paragraphs, headings, lists, tables, etc.) map directly. ADF-only nodes (panels, mentions, colored text, etc.) are embedded as invisible HTML comment annotations in the Markdown output, so the full structure survives a roundtrip:

ADF → Markdown (with annotations) → ADF   ✅ lossless

Without annotations, standard Markdown elements still convert to valid ADF — just without the ADF-specific extras:

Plain Markdown → ADF   ✅ works (standard elements only)

How Annotations Work

When ADF contains features that Markdown can't express natively (e.g., panels, mentions, colored text), Marklas wraps a readable Markdown fallback in HTML comment annotations:

<!-- 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.

These annotations are invisible when rendered as Markdown (GitHub, editors, etc.), but Marklas can parse them back to reconstruct the original ADF structure exactly.

Installation

pip install marklas

Usage

from marklas import to_adf, to_md

Markdown → ADF

Any standard Markdown converts to valid ADF:

adf = to_adf("""
## Project Update

The release is **on track**. Key changes:

- Refactored auth module
- Fixed 3 critical bugs

| Component | Status |
| --------- | ------ |
| Backend   | Done   |
| Frontend  | WIP    |
""")

ADF → Markdown

ADF-only features (panels, mentions, colored text, etc.) are preserved as HTML comment annotations — invisible in rendered Markdown, but fully restorable:

md = to_md(adf_with_panel)

<!-- adf:panel {"panelType": "warning"} -->
Do **not** deploy on Fridays.
<!-- /adf:panel -->

To get clean Markdown without annotations, pass annotate=False. ADF-only attributes are stripped and only standard Markdown elements remain:

clean_md = to_md(adf_with_panel, annotate=False)

Do **not** deploy on Fridays.

Roundtrip

original_adf = fetch_confluence_page()     # complex ADF
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	102,706	33,343	12,454
Bytes	625 KB	99 KB	38 KB
Reduction	—	3.1x / 6.3x	8.2x / 16.5x

Measured on a real Confluence page using GPT-4o tokenizer (tiktoken).

Notes

• Table cells: Non-paragraph content inside table cells (lists, code blocks, etc.) is converted to inline HTML (<ul>, <code>, <br>) to fit within GFM table syntax.
• Markdown-only features: Raw HTML blocks/inlines and other Markdown-specific constructs that have no ADF equivalent are silently dropped during conversion.

Development

uv sync --extra dev
uv run pytest -v