Formato del documento

Postext lee un dialecto de Markdown deliberadamente reducido.

El analizador es un tokenizador escrito a mano, no una implementación completa de CommonMark, así que el formato de entrada es limitado y predecible. Se persigue un doble objetivo: que el motor sea pequeño y rápido, y que los documentos pasen sin ningún esfuerzo de Postext a cualquier otro lector de CommonMark (Obsidian, Pandoc, VS Code…) y viceversa. Todo lo que no aparece en esta página se trata como texto normal o se descarta del texto en línea.

Si generas el documento por código, la función parseMarkdown (véase Configuración › Analizar el Markdown) te da exactamente la estructura de bloques que recibe el motor de maquetación.

#Frontmatter

Un documento puede empezar con un bloque opcional de frontmatter en YAML, delimitado por dos líneas ---:

---
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. La función devuelve el objeto de metadatos ya analizado, el Markdown restante y la posición (en caracteres) en la que empieza el cuerpo, algo útil si necesitas trasladar errores o posiciones del cursor al texto original.

El frontmatter se analiza con gray-matter, así que se acepta YAML de cualquier forma. Postext solo tiene en cuenta title, subtitle, author y publishDate; las demás claves se conservan en PostextContent.metadata para que las uses como quieras.

Un bloque que no es YAML válido (unas comillas sin cerrar, texto detrás de un valor entre comillas) no detiene la maquetación: extractFrontmatter no devuelve metadatos, toma como cuerpo el texto que sigue al --- de cierre y deja en error el motivo que da el analizador. El documento se compone sin sus metadatos, y la compilación añade un aviso invalidFrontmatter a contentWarnings (el Sandbox lo muestra como Frontmatter no válido).

YAML asigna un tipo a cada valor: 1984 es un número; 2026-04-15, una fecha, y [Ana Gil, Luis Paz], una lista. Postext imprime esos cuatro campos como texto, sea cual sea su tipo:

• un número, en su forma decimal simple, y un booleano, como true o false (title: 1984 imprime 1984). YAML lee los números como valores, no cifra a cifra: 1.50 imprime 1.5; 017 (octal), 15, y 1:30 (base 60), 90;
• una fecha, como el día del calendario escrito en el idioma del documento (el ajuste locale o, si falta, el idioma de la separación silábica): publishDate: 2026-04-15 imprime 15 de abril de 2026 en español, April 15, 2026 en inglés y 15. April 2026 en alemán. Las fechas en árabe usan el calendario gregoriano, salvo que la etiqueta indique otro (ar-u-ca-islamic imprime la fecha de la hégira), y las cifras que corresponden a la etiqueta (ar-EG: ١٥ أبريل ٢٠٢٦; ar-u-nu-latn: 15 أبريل 2026). Si la fecha incluye una hora, se imprime el día que corresponde en UTC y la hora se descarta: 2026-09-24T23:30:00-05:00 son las 04:30 UTC del día 25, así que imprime 25 de septiembre de 2026;
• una lista, como sus elementos separados por comas (author: [Ana Gil, Luis Paz] imprime Ana Gil, Luis Paz).

Pon el valor entre comillas para que se imprima exactamente como está escrito, ya sea un número que deba conservar sus cifras o una fecha que deba conservar su día: publishDate: "15/04/2026", title: "1984". Ese texto llega a doc.metadata, a los marcadores ({title}, {publishDate}…) y al título y el autor del PDF. Si uno de los cuatro campos no tiene forma de texto (un mapa anidado, un title: vacío), queda fuera de doc.metadata. extractFrontmatter sigue devolviendo los valores con el tipo que les dio YAML; metadataText(value, locale) da el texto que Postext imprime para cada uno.

#Construcciones de bloque

Postext reconoce siete tipos de bloque de texto y los listados de código, además de las directivas y las inserciones de recursos, que tienen su propia página. Un bloque termina siempre con una línea en blanco o donde empieza otro bloque.

Se tolera una sola línea en blanco entre dos elementos de lista: la lista sigue siendo una. Dos o más líneas en blanco seguidas la terminan.

Se aceptan listas de distintos tipos en la misma profundidad (puedes pasar de no ordenada a ordenada a mitad de la lista), pero el motor numera cada tramo por separado. En la práctica, usa un solo tipo por nivel, salvo que tengas un motivo para mezclarlos.

#Atributos de encabezado

Una línea de encabezado puede terminar con un bloque de atributos entre llaves, con la misma sintaxis clave="valor" que usan las directivas:

# El largo camino {author="I. Zango Martín" year=1998}

Las llaves y su contenido se eliminan del texto del encabezado (el título del ejemplo se muestra como El largo camino) y se guardan en el encabezado como attrs. Los diseños pueden usarlos como marcadores {attr.<clave>}: en el diseño avanzado del propio encabezado y en las cabeceras y pies de página, donde toman el valor del H1 del capítulo en curso. Solo se reconoce un bloque equilibrado, sin llaves anidadas, situado al final de la línea, detrás de un espacio o, como los títulos chinos se escriben sin espacio, justo detrás de un carácter chino o japonés (# 回目{style="x"}). El bloque solo se toma si la sintaxis de atributos que se describe más abajo puede leerlo entero: {x, y}, {紅樓|hóng lóu} y un {} suelto se quedan en el título, igual que los indicadores sueltos pegados al título (# 第一回{draft}). Los atributos se separan con espacios, así que un bloque con comas ({a="1", b="2"}) y el {.clase} de Pandoc también se quedan en el título. El identificador de Pandoc, {#id}, sí se lee: equivale a id="…" y da al encabezado un nombre para las referencias cruzadas. Una clave escrita en otra escritura se lee y se descarta con un aviso (véase más abajo), así que # 回目{style="x" 作者=曹雪芹} sigue tomando style. Consulta Configuración: cabeceras y pies de página.

Un valor que imprime un texto de diseño puede ocupar varias líneas: los dos caracteres \n empiezan una línea nueva, sea cual sea el overflow del elemento (to="Firma X\nStrasse 1\n10115 Berlin" imprime una dirección de tres líneas). Si el elemento tiene inlineMarks, las marcas en línea del valor también se aplican: authors="Ana Ruiz^1^, Luis Gil^2^" compone como superíndices los números de afiliación. Este escape solo vale en los valores de atributo (y en los textos del propio diseño): los caracteres \n en el texto de un encabezado, por ejemplo dentro de un código en línea, se imprimen tal cual.

Dos atributos tienen un significado propio. style="<id>" aplica al encabezado un estilo de encabezado con nombre: un prólogo o una lista de autores con su propio diseño de apertura, sus titulillos, su geometría de página y su tipografía del texto base, y sin número de capítulo cuando el estilo indica numbered: false. toc="false" (o "true") decide, por encima de lo configurado, si el encabezado aparece en :::toc:

# Prólogo {style="preliminar"}
 
# Índice {style="preliminar" toc="false"}

Otros dos cambian lo que imprime un encabezado y cómo se cuenta. hidden="true" (o "false") se impone al hidden del nivel o del estilo del encabezado: un encabezado oculto no imprime nada ni ocupa sitio (ni en el flujo ni dentro de un recuadro :::callout), pero sigue abriendo su página, se cuenta y aparece en el índice, en los titulillos con {chapterTitle} y en los marcadores del PDF. jidori=N reparte uniformemente un encabezado de una sola línea en el espacio de N de sus propios caracteres (字取り: # 序章 {jidori=3} imprime 序　章), y jidori=0 desactiva el espaciado uniforme que fija su nivel o su estilo (véase Configuración › Configuración por nivel). indent=N desplaza un solo encabezado N caracteres del texto base desde el principio de la línea (字下げ: ## 一 {indent=5}), por encima del indent de su nivel o de su estilo; un número sin unidad cuenta cuadratines del texto base, 0 coloca el encabezado al principio de la línea, y funciona igual en texto vertical y horizontal. firstLineIndent=N sangra solo la primera línea de un encabezado, por encima del firstLineIndent de su nivel o de su estilo, y las demás líneas empiezan donde las coloca indent (los títulos de la norma GB/T 9704: ## 关于加强管理的通知 {firstLineIndent=2}); lee las longitudes igual que indent, y 0 desactiva la del nivel. startAt=N, un entero positivo, pone el contador del nivel del encabezado en N en lugar de hacerlo avanzar; los encabezados siguientes cuentan a partir de ahí, también en los capítulos posteriores, y los niveles inferiores se reinician bajo él como siempre. Con un estilo de encabezado que numera los apéndices con letras (numberingTemplate: 'Apéndice {1:A}'), el primer apéndice reinicia la cuenta para que se lea Apéndice A en lugar de seguir la numeración de los capítulos:

# A mi madre {hidden="true" toc="false"}
 
# Cuestionario {style="apendice" startAt=1}
 
# Datos en bruto {style="apendice"}

#Letras capitulares

Un párrafo empieza con capitular cuando la fija el nivel o el estilo de su encabezado, o el estilo de párrafo de su grupo :::paragraphs (véase Configuración › Letras capitulares): la primera letra se compone en grande junto a las primeras líneas, que se acortan para dejarle sitio. El párrafo no necesita ninguna marca: el texto se escribe como siempre, y la letra sigue formando parte de su palabra al copiar, al buscar y en el mapa de origen. El atributo dropcap la cambia para un capítulo o para un grupo:

# Perdidos {dropcap=false}
 
# Las minas {dropcap=2}
 
:::paragraphs{style="entrada" dropcap}
La lámpara de la primera entrada se abre con una capitular.
:::

En la línea de un encabezado, dropcap=false quita al párrafo que sigue a ese encabezado la capitular que fija su nivel o su estilo, dropcap=N la compone sobre N líneas, y dropcap a secas le pone una (de tres líneas, con la letra del párrafo) cuando el nivel no fija ninguna. En la línea de apertura de un :::paragraphs, el atributo hace lo mismo con el primer párrafo del grupo, o con todos si el estilo indica each: true. Para encontrar el párrafo que sigue a un encabezado, se saltan los delimitadores, las directivas, los recuadros que salieron del flujo y las figuras flotantes; un párrafo dentro de un recuadro, de un elemento de lista, de una cita o de un poema nunca lleva capitular. Desde postext 1.23.

En una página compuesta, los marcos son texto corrido: :::paragraphs{style="apertura" dropcap} en un marco abre su primer párrafo con la capitular. Dentro de un recuadro :::callout, los párrafos no llevan capitular, y si se pide ahí, salta un aviso dropCap.

#Bloques de código

Un listado va entre dos líneas delimitadoras de tres o más comillas invertidas (o de tres o más virgulillas), cada una en su propia línea y con un máximo de tres espacios delante. Todo lo que hay entre ellas se conserva tal como está escrito: los espacios iniciales y las series de espacios, los tabuladores, las líneas en blanco y las líneas que empiezan por #, -, 1., >, $ o :::. Dentro no se lee nada como Markdown: ni énfasis, ni :ref, ni fórmulas, ni chips, ni directivas, ni encabezados. La línea de cierre usa el mismo carácter que la de apertura y es al menos igual de larga, así que un listado que muestra un delimitador va entre delimitadores más largos o de virgulillas:

```bash {title="copia.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copia las fotos al disco de respaldo
rsync -a --delete ~/Fotos/ /Volumes/Respaldo/Fotos/
echo "hecho: $(date)"
```

La cadena de información que sigue al delimitador de apertura indica el lenguaje (su primera palabra: js, ts, python, bash, console, json…), y el resto se lee como atributos, con la sintaxis de atributos, entre llaves o sin ellas (title="app.js" lineNumbers). Lo que siga al lenguaje y no sea un atributo es el título: ```console Terminal y ```python normalize.py imprimen Terminal y normalize.py sobre el listado.

Un delimitador termina el párrafo anterior, haya línea en blanco o no, y el texto que sigue a la línea de cierre empieza un párrafo nuevo. Un listado sin cerrar llega hasta el final del texto y se marca con un aviso (unclosedCodeBlock). Un bloque de código dentro de un :::callout es una caja anidada en él; dentro de :::paragraphs, el listado conserva el estilo de código, no el de párrafo. Postext no permite continuar un elemento de lista en otro bloque, así que un bloque de código detrás de un elemento de lista cierra la lista. Las marcas de índice y las anclas escritas dentro de un listado se quedan tal como están.

El código sangrado (cuatro espacios o un tabulador, tras una línea en blanco) solo se lee como listado si codeStyle.indentedCode está activado: en los textos de Postext es habitual sangrar con espacios, y los espacios iniciales son los que anidan los elementos de lista.

El aspecto de un listado (su letra, su caja, el ancho del tabulador, qué ocurre con una línea más ancha que la caja, los números de línea, los colores de sus elementos) lo fija codeStyle; véase Configuración › Listados de código. El código en línea (`x`) usa la letra del texto, salvo que codeStyle.inline le asigne otra. Un libro guardado antes de postext 1.23 que tenga bloques de código en el texto los sigue leyendo como entonces, como Markdown (codeStyle.blocks: false). Desde postext 1.23.

#Qué no se admite

Postext no reconoce estas funciones de CommonMark. Se tratan como texto normal (y, por tanto, aparecen tal cual en la salida) o se descartan sin aviso:

• Encabezados de tipo Setext: los que se subrayan con === / ---. Usa encabezados ATX (#).
• HTML sin procesar: las etiquetas <tag> no se interpretan. Tampoco se admiten etiquetas de tipo MDX: el texto de origen de Postext es Markdown puro.
• Filetes horizontales: ---, ***, ___.
• Tablas: las tablas con barras verticales no se analizan. Las tablas se modelan como recursos estructurados en PostextContent.resources.
• Enlaces por referencia: [texto][id] con su bloque de definición.
• Enlaces automáticos: <https://example.com>.
• Saltos de línea con dos espacios al final: los espacios se eliminan. Termina la línea con una barra invertida (véase Saltos de línea).
• Tachado: ~~texto~~. Por ahora, el tachado solo se usa para las tareas completadas.
• Notas al margen: no están implementadas, y el motor ignora PostextContent.notes aunque los tipos lo acepten. Las notas al pie y las notas de final de capítulo se escriben con [^id] (véase Notas al pie); hasta postext 1.5 había que componerlas como texto.

Esta lista irá menguando con el tiempo. Mientras tanto, todo lo que no figure expresamente entre lo admitido debe considerarse texto literal.

Más allá de la sintaxis, el árabe y las demás escrituras de derecha a izquierda se componen de derecha a izquierda, con el algoritmo bidireccional y la encuadernación a la derecha (véase Composición árabe). El chino se compone en horizontal y en vertical, con el corte de líneas, los anchos de puntuación, la justificación entre caracteres, las marcas, el ruby y el warichu que espera cada región (véase Composición china). El japonés se compone con sus propias reglas: kinsoku, espaciado de los yakumono, furigana, marcas de énfasis, marcas de kanbun y notas (véase Composición japonesa); el coreano usa el mismo compositor con las reglas de China continental. Postext incluye patrones de separación silábica para ocho idiomas, y textos integrados para esos ocho, el chino, el japonés y el árabe. Consulta Idiomas y escrituras.

#Normas de redacción

Unas pocas normas marcan la diferencia entre un documento que se lee sin problemas y uno que da sorpresas:

• 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 une al párrafo anterior.
• Las líneas en blanco de más no añaden espacio. Tres líneas en blanco separan dos bloques exactamente igual que una. Si quieres más espacio entre ellos, escribe una línea :::space.
• Sangra un elemento anidado hasta el texto del elemento de arriba. Dos espacios bajo una viñeta (- ), tres bajo 1. y cuatro bajo 10. , igual que anida las listas CommonMark; dos espacios bajo 1. también anidan. Un elemento se anida bajo el elemento abierto más cercano cuya marca esté al menos dos columnas a su izquierda, así que un solo espacio no anida nada y nunca se salta un nivel, sea cual sea el incremento (hasta postext 1.15, la profundidad era floor(espacios / 2) + 1, y un 1. bajo 1. quedaba en el nivel 4). Un tabulador avanza hasta el siguiente múltiplo de cuatro columnas. La profundidad máxima es 5.
• No sangres el primer elemento de una lista. Los elementos de nivel 1 empiezan en la columna 0. El primer elemento de una lista abre el nivel 1 por mucho que esté sangrado (hasta postext 1.15, sus espacios iniciales aumentaban la profundidad), así que para anidar hace falta un elemento superior.
• Las marcas de tarea van entre corchetes, con un único espacio. [ ], [x], [X], sin variantes. [*] o [-] no son marcas de tarea: se muestran 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 las tablas están en resources. El ![alt](src) en línea se elimina precisamente porque las imágenes en línea impiden colocarlas teniendo en cuenta las columnas. Declara cada imagen como recurso y remite a ella por su id: el motor decide entonces si flota, si corta la columna o si pasa al principio de la página siguiente.
• Escapa el signo de dólar con \$ cuando no se trate de matemáticas. Postext interpreta $…$ como LaTeX en línea, así que un $ suelto en el texto empieza una fórmula. Los precios, los indicadores de la terminal y cualquier otro dólar suelto deben escribirse como \$.
• Escribe el marcado en ASCII, también en los textos chinos y japoneses. Un método de entrada chino o japonés produce formas de ancho completo: ：：： para un delimitador, ＃ para un encabezado, ［＾1］ para una llamada de nota, ｛…｝ para los atributos, ＊＊ para la negrita. Se imprimen como texto, y la compilación marca la línea con un aviso fullwidthMarkup que indica la forma ASCII que hay que escribir. Los valores de los atributos pueden estar en cualquier escritura e ir entre “…” o 「…」; las claves siguen siendo ASCII.

#Ejemplo completo

Un documento breve que usa 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.
   1. Más ajustada en anchos cortos.
   2. 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 fórmulas en bloque quedan centradas sobre la rejilla de línea base:
 
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$

Al pasar por el motor de maquetación, ese mismo documento produce un VDTDocument estructurado cuyas páginas contienen cada uno de estos bloques como entradas con tipo; en la página Arquitectura verás cómo los bloques se convierten en geometría.