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, use Transformer:

from marklas import Transformer, parse_md, render_adf
from marklas.ast import CodeBlock, Expand, Extension, Media, Node

t = Transformer()

# Replace: return a Node to substitute the original
@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

# Splice: return a list[Node] to expand one node into many
@t.register(CodeBlock)
def _(node: CodeBlock) -> list[Node] | None:
    if node.language == "mermaid":
        return [
            Expand(title="mermaid source", content=[node]),
            Extension(
                extension_key="mermaid-macro",
                extension_type="com.example.mermaid",
                parameters={"code": "".join(c.text for c in node.content)},
            ),
        ]
    return None

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

A handler returns one of three values:

Return	Effect
`None`	Skip — pass to the next handler, or leave unchanged
`Node`	Replace the original node
`list[Node]`	Splice multiple nodes in place of the original

Multiple handlers can be registered for the same type; they run in registration order and the first non-None result wins. The tree is traversed bottom-up, and nodes returned by a handler are not revisited.

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	2,173,468	858,970	560,765
Reduction	—	2.5x	3.9x

Measured on 204 real Confluence pages (compact JSON) using GPT-4o tokenizer (tiktoken).

Documentation

Format Reference — how each ADF node maps to Markdown
ARCHITECTURE.md — parser internals and conversion fidelity (for contributors)

Development

uv sync --extra dev
uv run pytest -v

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

marklas-0.8.3.tar.gz (48.5 kB view details)

Uploaded Jul 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

marklas-0.8.3-py3-none-any.whl (56.9 kB view details)

Uploaded Jul 9, 2026 Python 3

File details

Details for the file marklas-0.8.3.tar.gz.

File metadata

Download URL: marklas-0.8.3.tar.gz
Upload date: Jul 9, 2026
Size: 48.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for marklas-0.8.3.tar.gz
Algorithm	Hash digest
SHA256	`fb59083952fb71ea69770e08b5b8ae4bd0873e5e0d751e31371b17883a403efa`
MD5	`be516668324cd831c6dcd1c95c32e90d`
BLAKE2b-256	`b6360443cafb10853d1ec298e5b84add81c271c8f4c056fb1899af81310ed79f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for marklas-0.8.3.tar.gz:

Publisher: publish.yml on byExist/marklas

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: marklas-0.8.3.tar.gz
- Subject digest: fb59083952fb71ea69770e08b5b8ae4bd0873e5e0d751e31371b17883a403efa
- Sigstore transparency entry: 2124243871
- Sigstore integration time: Jul 9, 2026
Source repository:
- Permalink: byExist/marklas@14f566131d93fefba666c3f85ce44af0c99291da
- Branch / Tag: refs/tags/v0.8.3
- Owner: https://github.com/byExist
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@14f566131d93fefba666c3f85ce44af0c99291da
- Trigger Event: release