Primeros pasos

El camino más corto desde "acabo de instalar markast" hasta "estoy enviando contenido a mi cliente". Todo aquí usa los valores por defecto; los capítulos siguientes cubren la configuración.

Instalación

pip install markast

Extras opcionales:

  • pip install markast[test] — añade pytest para correr la suite de tests.
  • pip install linkify-it-py — necesario si quieres detección automática de URLs (feature autolinks). Sin él, esa única feature se desactiva silenciosamente — el resto sigue funcionando.

Parsea Markdown

from markast import parse

doc = parse("# Hola\n\nUn párrafo con **negrita** y un [enlace](https://example.com).")

print(doc.to_json(indent=2))

Salida (abreviada):

{
  "type": "document",
  "version": "1.0",
  "warnings": [],
  "children": [
    { "type": "heading", "level": 1, "children": [
        { "type": "text", "value": "Hola" }
    ] },
    { "type": "paragraph", "children": [
        { "type": "text", "value": "Un párrafo con " },
        { "type": "bold", "children": [
            { "type": "text", "value": "negrita" }
        ] },
        { "type": "text", "value": " y un " },
        { "type": "link", "href": "https://example.com", "title": null,
          "children": [ { "type": "text", "value": "enlace" } ] },
        { "type": "text", "value": "." }
      ] }
  ]
}

Esa es toda la API para el caso más simple.

Render

parse() devuelve un Document. Las cuatro operaciones que usarás más:

doc.to_json(indent=2)   # str — el árbol estructurado, para transporte
doc.to_markdown()       # str — Markdown canónico, para UIs de edición
doc.to_html()           # str — HTML, para render server-side
doc.to_dict()           # dict — el árbol crudo subyacente

Inspeccionar warnings

El parser nunca lanza excepciones por contenido inválido. Si algo no es válido para renderizar en el cliente (imagen dentro de heading, widget desconocido, …), emite un diagnóstico:

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.
!
Los diagnósticos nunca bloquean el parseo. Pase lo que pase, recibes un AST válido que puedes enviar. El catálogo completo está en el capítulo Extender la librería.

Usa un widget registrado

markast trae varios widgets pre-registrados. Los más comunes son los admonitions:

from markast import parse

md = """
:::tip title="Consejo"
Puedes anidar **markdown** aquí.
:::
"""

doc = parse(md)
print(doc.to_html())
# <aside class="admonition admonition-tip"><header>Consejo</header>
#   <div class="admonition-body"><p>Puedes anidar <strong>markdown</strong> aquí.</p></div>
# </aside>

Otros builtins: note, info, warning, caution, danger, card, video, code-group, code-collapse, tabs, steps, badge. Sigue en el capítulo Widgets para el catálogo completo y cómo escribir los tuyos.

A dónde ir después

Vista general Referencia del AST