Getting started

The shortest possible path from "I just installed markast" to "I'm shipping content to my client app." Everything here uses defaults; later chapters cover configuration.

Install

pip install markast

Optional extras:

  • pip install markast[test] — pulls in pytest for running the test suite.
  • pip install linkify-it-py — required if you want bare-URL detection (the autolinks feature). Without it, that one feature is silently disabled — everything else still works.

Parse some Markdown

from markast import parse

doc = parse("# Hello\n\nA paragraph with **bold** and a [link](https://example.com).")

print(doc.to_json(indent=2))

Output (abbreviated):

{
  "type": "document",
  "version": "1.0",
  "warnings": [],
  "children": [
    { "type": "heading", "level": 1, "children": [
        { "type": "text", "value": "Hello" }
    ] },
    { "type": "paragraph", "children": [
        { "type": "text", "value": "A paragraph with " },
        { "type": "bold", "children": [
            { "type": "text", "value": "bold" }
        ] },
        { "type": "text", "value": " and a " },
        { "type": "link", "href": "https://example.com", "title": null,
          "children": [ { "type": "text", "value": "link" } ] },
        { "type": "text", "value": "." }
      ] }
  ]
}

That's the entire API for the simplest case.

Render

parse() returns a Document. The four operations you'll use most often:

doc.to_json(indent=2)   # str — the structured tree, for transport
doc.to_markdown()       # str — canonical Markdown, for editing UIs
doc.to_html()           # str — HTML, for server-side rendering
doc.to_dict()           # dict — the raw underlying tree

Inspect warnings

The parser never raises on bad content. If something is invalid for client rendering (an image inside a heading, an unknown widget, …), it emits a diagnostic:

doc = parse("# ![alt](logo.png)")
for w in doc.warnings:
    print(w["code"], w["message"])
# W001  Image inside h1 heading — alt text used as content.
!
Diagnostics never block parsing. Whatever is reported, you still get a valid AST you can ship. The full diagnostic catalogue lives in the Extending chapter.

Use a registered widget

markast comes with several widgets pre-registered. The most common are admonitions:

from markast import parse

md = """
:::tip title="Pro tip"
You can nest **markdown** here.
:::
"""

doc = parse(md)
print(doc.to_html())
# <aside class="admonition admonition-tip"><header>Pro tip</header>
#   <div class="admonition-body"><p>You can nest <strong>markdown</strong> here.</p></div>
# </aside>

Other built-ins: note, info, warning, caution, danger, card, video, code-group, code-collapse, tabs, steps, badge. Read on in the Widgets chapter for the full catalogue and how to write your own.

Where to go next

Overview AST reference