Referencia del AST

Especificación de cada tipo de nodo que el parser puede producir. Usa este capítulo cuando escribas un renderer cliente.

Document (raíz)

{
  "type":     "document",
  "version":  "1.0",
  "warnings": [ {"code": "W001", "message": "...", "context": "..."} ],
  "children": [ /* nodos block */ ],
  "meta":     {}
}

Campo	Tipo	Notas
`version`	string	Sube cuando hay cambios incompatibles. Actualmente `"1.0"`.
`warnings`	array	Lista de diagnósticos. Siempre presente (puede estar vacía).
`children`	array	Nodos block. Siempre presente (puede estar vacía).
`meta`	object	Bolsa abierta para que las transformaciones agreguen datos (TOC, slugs, …). Puede estar ausente.

Nodos block

heading

{ "type": "heading", "level": 2, "children": [ /* inline */ ], "id": "section-id" }

level ∈ 1–6.
id lo añade la transformación slugify; ausente en otro caso.
Los hijos inline están restringidos (regla W001). Las imágenes se convierten en su alt text.

paragraph

{ "type": "paragraph", "children": [ /* inline */ ] }

blockquote

{ "type": "blockquote", "children": [ /* block */ ] }

code_block

{
  "type":            "code_block",
  "language":        "python",
  "value":           "print('hi')",
  "filename":        "main.py",
  "highlight_lines": [1, 3, 4, 5]
}

filename y highlight_lines se omiten cuando no aplican.

image (block)

{ "type": "image", "src": "https://...", "alt": "descripción", "title": null }

Se produce cuando una línea de Markdown contiene exactamente una imagen y nada más. Las líneas mixtas producen inline_image.

list

{
  "type":     "list",
  "ordered":  false,
  "start":    1,
  "children": [ /* list_item */ ]
}

start solo está presente en listas ordenadas.

list_item

{
  "type":     "list_item",
  "checked":  true,
  "children": [ /* block o inline */ ]
}

checked es true/false para items de tasklist GFM, ausente en items normales.

table, table_row, table_cell

{
  "type": "table",
  "head": { "type": "table_head", "rows": [ /* row */ ] },
  "body": { "type": "table_body", "rows": [ /* row */ ] }
}

{
  "type":      "table_cell",
  "is_header": true,
  "align":     "center",
  "children":  [ /* inline */ ]
}

align ∈ "left" | "center" | "right" | null. Contenido block dentro de celdas está prohibido (regla W002).

divider

{ "type": "divider" }

widget

{
  "type":   "widget",
  "widget": "tip",
  "props":  { "title": "Consejo" },
  "slots":  {
    "default": [ /* nodos block */ ],
    "footer":  [ /* nodos block */ ]
  }
}

slots siempre contiene la clave "default" (posiblemente un array vacío). Ver el capítulo Widgets.

html_block

{ "type": "html_block", "value": "<div>raw html</div>" }

El parser no interpreta HTML — pasa los bloques tal cual y emite un diagnóstico informativo W007.

footnote_def

{ "type": "footnote_def", "label": "1", "children": [ /* block */ ] }

Nodos inline

Tipo	Campos
`text`	`value` (string)
`bold`	`children`
`italic`	`children`
`bold_italic`	`children`
`code_inline`	`value`
`strikethrough`	`children`
`underline`	`children`
`link`	`href`, `title` (o `null`), `children`
`inline_image`	`src`, `alt`, `title`
`softbreak`	—
`hardbreak`	—
`footnote_ref`	`label`

Exportar JSON Schema

La función markast.json_schema() devuelve un JSON-Schema que describe todo lo anterior. Pásalo a un validador en tu cliente para hacer cumplir la compatibilidad de formas, o aliméntaselo a un generador de código para crear modelos tipados.

import json
from markast import json_schema

with open("ast.schema.json", "w") as f:
    json.dump(json_schema(), f, indent=2)