Formato del documento

Postext lee un dialecto de markdown deliberadamente reducido.

El parser es un tokenizador escrito a mano — no una implementación completa de CommonMark — por lo que el formato de entrada es estrecho y predecible. La intención es doble: mantener el motor pequeño y rápido, y hacer que los documentos sean trivialmente portables entre Postext y cualquier otro lector de CommonMark (Obsidian, Pandoc, VS Code…). Todo lo que no aparezca en esta página se trata como texto plano o se elimina del flujo en línea.

Si construyes el documento por código, la función parseMarkdown (ver Configuración › Parseo) te devuelve exactamente la misma estructura de bloques que consume el motor de composición.

#Frontmatter

Un documento puede empezar con un bloque opcional de frontmatter YAML encerrado entre marcadores ---:

---
title: Capítulo uno
author: Jane Doe
publishDate: 2026-04-15
---
 
# Capítulo uno
 
La historia empieza aquí…

Llama a extractFrontmatter(source) para separar el frontmatter del cuerpo. El objeto de metadatos parseados se devuelve junto con el markdown restante y el desplazamiento (en caracteres) donde empieza el cuerpo — útil si necesitas mapear errores o posiciones de cursor al documento original.

El frontmatter se parsea con gray-matter, por lo que se acepta cualquier forma válida de YAML. Postext solo consulta title, subtitle, author y publishDate; las demás claves se conservan en PostextContent.metadata y quedan disponibles para tu uso.

#Construcciones de bloque

Postext reconoce siete tipos de bloque. Los bloques siempre terminan al encontrar una línea en blanco o el inicio de otro bloque.

Se tolera una única línea en blanco entre dos elementos de lista — la lista se mantiene unida. Dos o más líneas en blanco consecutivas terminan la lista.

Se aceptan listas de tipos mixtos a la misma profundidad (puedes pasar de no ordenada a ordenada a mitad de recorrido), pero el motor trata cada tramo por separado a efectos de numeración. En la práctica, conviene mantener un único tipo por profundidad salvo que haya un motivo claro para mezclarlos.

#Formato en línea

El marcado en línea se reconoce dentro de cualquier bloque de texto (encabezados, párrafos, citas, elementos de lista).

Marcado	Sintaxis	Notas
Negrita	negrita o negrita	Se renderiza con bodyText.boldFontWeight. Un bodyText.boldColor opcional anula el color general del cuerpo para los tramos en negrita.
Cursiva	cursiva o cursiva	Se renderiza con la variante cursiva de la fuente actual. Un bodyText.italicColor opcional anula el color general del cuerpo para los tramos en cursiva.
Negrita cursiva	ambas o ambas	Se combinan ambos estilos.
Código en línea	código	Las comillas invertidas se eliminan; el tramo se renderiza como texto plano. El estilo diferenciado para código está en el roadmap.
Enlace	texto	El texto visible permanece en el flujo; la URL se descarta en el renderizador actual. El soporte de enlaces está en el roadmap.
Imagen		El markdown de imagen en línea se elimina del texto. Las imágenes deben declararse en PostextContent.resources para que el motor las coloque según las reglas de resourcePlacement.
Matemáticas en línea	$…$	Una fórmula LaTeX que fluye con el texto que la rodea, p. ej. $e^+1=0$. Se compone con MathJax y se renderiza como trazos vectoriales en todos los backends. Las fórmulas cuya ascendente o descendente se salga de la caja de línea se escalan hacia abajo para no romper la rejilla vertical. Usa \$ para un signo de dólar literal.

#Fórmulas matemáticas

El soporte matemático forma parte del formato de documento de primer nivel. Postext parsea $…$ para fórmulas en línea y $$…$$ para fórmulas en display (bloque), y las renderiza con MathJax en modo SVG. Los mismos trazos vectoriales alimentan los tres backends, de modo que la vista previa en canvas, la exportación HTML y la salida PDF coinciden píxel a píxel — y el PDF se mantiene completamente vectorial sea cual sea el nivel de zoom.

• En línea: $…$. Se reconoce dentro de cualquier bloque de texto (párrafo, encabezado, cita, elemento de lista). Aporta una única caja atómica no partible a la línea; Knuth-Plass la trata como una palabra que no puede separarse. Si la altura natural de la fórmula rompería la caja de línea, se escala uniformemente para conservar la rejilla de línea base — las expresiones muy altas deben vivir en modo display.
• Display: $$…$$. Bien en una línea propia ($$\int_0^1 x^2\,dx$$) o vallada en varias líneas con marcadores $$ en sus propias líneas. Se renderiza centrada en la columna y ajustada a la rejilla de línea base con márgenes superior e inferior configurables (math.marginTop, math.marginBottom) — exactamente la misma corrección que usan los encabezados, de modo que el párrafo que sigue vuelve a caer sobre la rejilla.
• Escapado: \$ es un signo de dólar literal. Un delimitador $ o $$ sin cerrar produce una entrada unclosedMath en el panel de avisos con un ancla de fuente al que puedes saltar con un clic.
• Errores: el código TeX que MathJax rechaza (macros no definidos, errores de sintaxis) se refleja como un aviso invalidMath. La fórmula se sustituye por una pequeña caja roja para que la geometría del layout siga siendo válida.
• Configuración: la sección math de la configuración expone enabled, fontSizeScale (relativo al tamaño del cuerpo), color (hereda del cuerpo si se omite) y los márgenes del display.

La identidad de Euler $e^{i\pi}+1=0$ enlaza las cinco constantes fundamentales.
 
$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

#Qué NO se soporta

Postext no reconoce las siguientes características de CommonMark. O se tratan como texto plano (y por tanto aparecerán literalmente en la salida) o se descartan silenciosamente:

• Encabezados tipo setext — la forma con subrayado === / ---. Usa encabezados ATX (#).
• Bloques de código con cercas o con indentación — triple acento grave e indentación de 4 espacios. El código en línea funciona; el código multilínea se renderizará línea a línea como párrafos.
• HTML en crudo — las etiquetas <tag> no se interpretan. Tampoco se admiten etiquetas estilo MDX; la fuente Postext es markdown puro.
• Líneas horizontales — ---, ***, ___.
• Tablas — las tablas con pipes no se parsean. Las tablas se modelan como recursos estructurados en PostextContent.resources.
• Enlaces por referencia — [texto][id] con su bloque de definición.
• Autolinks — <https://example.com>.
• Tachado — ~~texto~~. El renderizador de tachado está reservado actualmente para tareas completadas.
• Marcas de nota al pie en markdown — [^1]. Las notas al pie viajan en PostextContent.notes y se referencian por id, no con sintaxis en línea.

Esta lista se irá reduciendo con el tiempo. Mientras tanto, cualquier cosa que no aparezca explícitamente arriba debe considerarse texto literal.

#Normas de redacción

Unas pocas normas marcan la diferencia entre un documento que se parsea limpiamente y uno que te sorprende:

• Deja una línea en blanco entre bloques. Dos párrafos separados por una línea en blanco son dos párrafos. Dos párrafos en líneas consecutivas se convierten en uno — cada línea se añade al párrafo anterior.
• Anida las listas con exactamente dos espacios por nivel. Un único espacio se parsea como un elemento de nivel 1. Tres o cuatro espacios se redondean hacia abajo al nivel 2 (el motor aplica floor(leading / 2) + 1, limitado a profundidad 5). Las tabulaciones no se reconocen — conviértelas a espacios.
• No indentes el primer elemento de la lista. Los elementos de nivel 1 empiezan en la columna 0. Cualquier espacio en blanco inicial aumenta la profundidad de forma implícita.
• Las marcas de tarea van entre corchetes con un único espacio. [ ], [x], [X] — sin variaciones. [*] o [-] no son marcas de tarea; se renderizan como texto literal.
• No se admiten citas dentro de listas. Empieza la cita en la columna 0, fuera de la lista.
• Las imágenes y tablas viven en resources. El ![alt](src) en línea se elimina precisamente porque rompe la colocación consciente de columnas. Declara cada imagen como recurso y refiérela por id — el motor decide si flota, rompe la columna o se desplaza al inicio de la página siguiente.
• Escapa los signos de dólar con \$ cuando no sean matemáticas. Postext interpreta $…$ como LaTeX en línea, así que un $ suelto en prosa iniciaría una fórmula. Precios, prompts de shell y cualquier otro dólar literal deben escribirse como \$.

#Ejemplo completo

Un documento breve que ejercita todas las construcciones admitidas:

---
title: El oficio del tipógrafo
author: Anónimo
---
 
# Apertura
 
Un buen libro se lee solo. El **lector** no debería percibir nunca el
trabajo del tipógrafo — solo la voz del autor.
 
## Qué hace legible al texto
 
Tres propiedades son determinantes:
 
1. El ancho de carro — entre 40 y 75 caracteres por línea.
2. La interlínea — entre 1,3 y 1,5 veces el tamaño de fuente.
   a. Más ajustada en anchos cortos.
   b. Más holgada en anchos largos.
3. El contraste entre cuerpo y encabezados.
 
Entre los fallos habituales están:
 
- Líneas que atraviesan toda la página.
- Encabezados que flotan sin un párrafo detrás.
- Huérfanas y viudas en los límites de columna.
 
> La tipografía es el oficio de dotar al lenguaje humano de una forma
> visual duradera.
> — Robert Bringhurst
 
### Lista de comprobación
 
- [x] Ancho de columna por debajo de 75 caracteres
- [x] Interlínea ajustada a 1,5
- [ ] Paso de huérfanas y viudas
- [ ] Corrección final
 
### Una nota sobre fórmulas
 
Las matemáticas en línea como $a^2 + b^2 = c^2$ fluyen con el texto que las
rodea, y las de display quedan centradas sobre la rejilla de línea base:
 
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$

Ese mismo documento, procesado por el motor, produce un VDTDocument estructurado cuyas páginas contienen cada uno de estos bloques como entradas tipadas — consulta la página de Arquitectura para ver cómo los bloques se convierten en geometría.