Transformaciones

Mutaciones AST → AST que se aplican después del parseo y antes de la serialización. Hornean comportamiento transversal sin contaminar el parser ni el renderer.

Transformaciones builtin

Identificador	Clase	Qué hace
`normalize`	`NormalizeText`	Une nodos text adyacentes, descarta los vacíos.
`slugify`	`SlugifyHeadings`	Añade un `id` estable a cada heading.
`toc`	`BuildTOC`	Construye un table-of-contents anidado en `doc.meta["toc"]`. Requiere `slugify`.
`linkify`	`Linkify`	Convierte URLs sueltas en texto a nodos `link`.
`smarttypography`	`SmartTypography`	Reemplaza guiones/comillas/puntos suspensivos por equivalentes tipográficos.

Aplícalas por nombre al construir el parser:

from markast import Parser

parser = Parser(transforms=["normalize", "slugify", "toc"])
doc = parser.parse("# Top\n\n## Sub\n\n# Top2")

print(doc.meta["toc"])
# [
#   {"level": 1, "text": "Top",  "id": "top",  "children": [
#       {"level": 2, "text": "Sub", "id": "sub", "children": []}
#   ]},
#   {"level": 1, "text": "Top2", "id": "top2", "children": []}
# ]

El orden importa

Las transformaciones corren en el orden que las listas. toc lee los ids que escribe slugify, así que slugify debe ir primero.

Escribir una transformación propia

from markast.transforms import Transform
from markast.ast import replace
from markast import NodeType


class StripDividers(Transform):
    """Quita cada regla horizontal del documento."""

    name = "strip-dividers"

    def apply(self, doc, config):
        return replace(doc, lambda n: None if n.get("type") == NodeType.DIVIDER else n)

Regístrala:

parser = Parser(transforms=[StripDividers])

Tres cosas a recordar: (1) recibe y devuelve un documento, (2) usa markast.ast.replace para reescrituras — maneja correctamente cada forma de contenedor, (3) usa doc["meta"] para exponer datos calculados en lugar de reescribir el árbol para acomodarlos.

Transformaciones vs. reglas

	Transformación	Regla (`markast.rules`)
Cuándo	Después del parseo, antes del render	Durante el parseo
Qué	Muta / anota el AST	Observa y reporta diagnósticos
Side effect	Cambia el output	Añade entradas a `doc.warnings`
Cuándo usar	Slugs, TOCs, autolinks, normalización	Validación transversal, lints

Usa una regla cuando quieres señalar algo. Usa una transformación cuando quieres cambiar algo.