PDF y Press
stxt-pdf convierte un documento STXT en un PDF accesible. stxt-press lo ofrece como servicio HTTP, con un editor web y una línea de comandos, y rellena plantillas con datos JSON.
Document (dev.stxt.pdf):
Language: es
Title: Informe del trimestre
Page:
Paper: A4
Margin: 50
Styles:
For element: Document
Typography:
Font: IBM Plex Sans
Size: 10
Section:
Heading 1:
Text: Informe del trimestre
Paragraph: Las ventas han crecido un 12 % respecto al trimestre anterior.El namespace dev.stxt.pdf describe el documento:
Page: el papel y los márgenes.Styles: el aspecto, con reglas por elemento, por estilo o por identificador.Section: el contenido, con encabezados, párrafos, tablas, imágenes, listas...
El motor calcula dónde va cada cosa, reparte el contenido en páginas y escribe el PDF.
Los dos proyectos leen el STXT con la biblioteca Java y no son
implementaciones del lenguaje: los errores de sintaxis y de esquema llevan los códigos
de la biblioteca (NODE_NOT_DEFINED_IN_SCHEMA...), y los del motor, los suyos.
El PDF
- Fuentes incrustadas, con los caracteres que se usan.
- Etiquetado para accesibilidad: PDF/UA-1, o PDF/UA-2 si se pide.
- PDF/A (2 y 3,
bya) si se pide, con ficheros adjuntos para Factur-X. - Marcadores, uno por encabezado.
- SVG: además del PDF, una imagen por página.
El motor es estricto. Cada elemento solo admite las propiedades que tienen sentido
en él, y ninguno tiene un aspecto propio: un Heading 1 no es más grande que un
Paragraph si un estilo no lo dice. Lo que no tendría efecto, se contradice o no cabe
es un error con su línea.
stxt-pdf
El motor, como biblioteca Java. Se publica en Maven Central como
dev.stxt:stxt-pdf.
Instalación
Java 17 o superior. La versión actual es la 0.18.1.
<dependency>
<groupId>dev.stxt</groupId>
<artifactId>stxt-pdf</artifactId>
<version>0.18.1</version>
</dependency>
O con Gradle:
implementation 'dev.stxt:stxt-pdf:0.18.1'
Convertir un documento
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import dev.stxt.InlineNode;
import dev.stxt.pdf.convert.Converter;
import dev.stxt.pdf.stxt.DocumentReader;
InlineNode doc = new DocumentReader().read(Path.of("informe.stxt"));
try (OutputStream out = Files.newOutputStream(Path.of("informe.pdf"))) {
Converter.create().toPdf(doc, out);
}
DocumentReader lee y valida el documento. Converter lo maqueta y escribe el PDF.
Un Converter se crea una vez y se puede usar desde varios hilos a la vez.
Opciones
Converter converter = Converter.builder()
.resources(new Resources(Path.of("mis-recursos"))) // otra carpeta de recursos
.styles(Path.of("estilos.stxt")) // un fichero de estilos aparte
.pdfA(PdfA.A3B) // PDF/A-3b
.build();
| Opción | Por defecto |
|---|---|
resources |
La carpeta resources/ del directorio de trabajo |
styles |
Ninguno. Cada llamada añade un fichero de estilos, y gana el último |
limits |
2000 páginas, 25 millones de píxeles por imagen y 20 MB por PDF, entre otros |
debug |
false. Con true, pinta el contorno de cada caja |
pdfUa |
1: PDF/UA-1. Con 2, PDF/UA-2, en PDF 2.0 |
pdfA |
Ninguno. PdfA.A2B, A2A, A3B o A3A |
exclude |
Ninguna. Las comprobaciones que dejan de ser un error, como Check.CONTRAST |
cancellation |
Ninguna. Cuándo parar todas las conversiones, por ejemplo tras un plazo |
Recursos
Las fuentes y las imágenes de un documento están en una carpeta de recursos:
resources/
fonts/ fuentes .ttf y .otf
images/ imágenes .png, .jpg y .svg
- Solo se usan las fuentes de
fonts/, nunca las del sistema. Cada fichero se reconoce por la familia, el peso y el estilo que declara dentro. - Una variante que no tiene fichero (un peso que la familia no trae) es un error: no se usa la más parecida.
Image: logos/acme.pngesresources/images/logos/acme.png. No se admiten rutas absolutas,..ni enlaces que salgan de la carpeta.- El repositorio incluye IBM Plex Sans, Serif y Mono, con licencia SIL Open Font License.
Errores
Todo error es un StxtPdfException con su tipo (kind()), su código (code()) y su
línea (line(), 0 si no es de una línea):
kind() |
Qué es |
|---|---|
INVALID_DOCUMENT |
Un error del documento: sintaxis, esquema o reglas del motor |
LIMIT |
El documento supera un límite: páginas, píxeles de una imagen, tamaño |
CANCELLED |
La conversión se paró por su cancellation |
RESOURCE |
La configuración de quien convierte: la carpeta de recursos, un fichero |
INTERNAL |
Un error del motor |
Documentación
Todo está en el repositorio, en castellano y en inglés:
- Manual: cómo se escribe un documento, del primero a cada elemento.
- Referencia: la regla exacta de cada comportamiento y las decisiones de diseño.
- Ejemplos: documentos reales (factura, carta, contrato, informe anual...) con su PDF.
stxt-press
El servicio, en un solo jar: una API HTTP, un editor web y una línea de comandos. La maquetación es la de stxt-pdf, y el relleno de los Slots, el de stxt-transform. La versión actual es la 0.6.1.
Arrancar
Con Docker, la imagen
ghcr.io/stxt-lang/stxt-press,
para linux/amd64 y linux/arm64:
docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/stxt-lang/stxt-press:0.6.1
En http://127.0.0.1:8080/ están el índice y el editor, con plantillas y documentos
de ejemplo. La imagen responde sin token a quien llegue a su puerto: 127.0.0.1 la
deja en la máquina.
Las plantillas, los documentos o los recursos propios sustituyen a los de la imagen:
docker run --rm -p 127.0.0.1:8080:8080 \
-v "$PWD/templates:/opt/stxt-press/templates:ro" \
-v "$PWD/documents:/opt/stxt-press/documents:ro" \
-v "$PWD/resources:/opt/stxt-press/resources:ro" \
ghcr.io/stxt-lang/stxt-press:0.6.1
Sin Docker, la carpeta
server/ del
repositorio es un servidor completo (el jar, su configuración, las fuentes y los
ejemplos). Necesita Java 17 o superior:
server/start.sh
Plantillas y Slots
Una plantilla es un documento dev.stxt.pdf con Slots, los lugares que esperan
un dato:
Document (dev.stxt.pdf):
Language: es
Title: Factura ${numero}
Page:
Paper: A4
Margin: 50
Styles:
For element: Document
Typography:
Font: IBM Plex Sans
Size: 10
Section:
Heading 1:
Text: Factura ${numero}
Paragraph: Cliente: ${cliente}
Paragraph: [lineas]${concepto}: ${importe} €Con estos datos:
{
"numero": "2026-0142",
"cliente": "Librería Atenea",
"lineas": [
{ "concepto": "Cuadernos A5", "importe": "120,00" },
{ "concepto": "Lápices HB", "importe": "36,00" }
]
}
El documento relleno, el que se maqueta, termina así:
Section:
Heading 1:
Text: Factura 2026-0142
Paragraph: Cliente: Librería Atenea
Paragraph: Cuadernos A5: 120,00 €
Paragraph: Lápices HB: 36,00 €
| Slot | Qué hace |
|---|---|
<var> |
Pone un valor, y termina el valor del nodo |
{objeto} |
Entra en un objeto |
[lista] |
Repite el nodo una vez por cada elemento |
${var} |
Pone un valor dentro de un texto, buscándolo desde el elemento hacia la raíz |
<?var>, {?objeto}, [?lista], ${?var} |
Opcional: sin datos, se quita el nodo (o el texto no recibe nada) |
$${ |
Un ${ literal |
Un Slot obligatorio sin datos es un error (SLOT_NO_DATA). Los Slots siguen
STXT Transform, que está en Genesis: pueden cambiar con ella.
Plantillas y documentos del servidor
El servidor imprime dos clases de ficheros, cada una desde su carpeta:
- Una plantilla (
/print): se rellena con los datos JSON de la petición, o con sus datos de ejemplo. - Un documento (
/documents): se imprime tal cual, sin datos.
templates/
.styles.stxt los estilos de todas las plantillas
facturas/
.styles.stxt los estilos de las plantillas de facturas/
factura.stxt la plantilla facturas/factura
factura.styles.stxt sus estilos propios
factura.json sus datos de ejemplo
Una plantilla se nombra por su ruta sin extensión (facturas/factura). Los estilos se
aplican desde la raíz hasta la plantilla, y gana el más cercano. Los documentos siguen
las mismas reglas, sin datos. Las carpetas se leen en cada petición: un fichero
cambiado cuenta sin reiniciar.
Rutas
| Ruta | Qué hace |
|---|---|
GET /print/{ruta} |
La plantilla, rellenada con sus datos de ejemplo |
POST /print/{ruta} |
La plantilla, rellenada con el cuerpo: los datos JSON tal cual |
GET /documents/{ruta} |
El documento, tal cual |
POST /render |
Cualquier documento: {"document": "...", "styles": ["..."], "data": {...}, "options": {...}} |
GET /schema |
El esquema dev.stxt.pdf del motor |
GET /health |
El estado y las versiones, sin token |
/print, /documents y /render responden con un PDF (?format=pdf, por defecto),
un SVG por página (?format=svg) o el documento relleno (?format=stxt).
&debug=true pinta el contorno de las cajas. La factura de ejemplo del servidor, con
sus datos de ejemplo y con los de un fichero:
curl -o factura.pdf http://127.0.0.1:8080/print/examples/invoice
curl -o factura.pdf -d @datos.json http://127.0.0.1:8080/print/examples/invoice
Un error es un cuerpo JSON con su código. Los de una conversión llevan también su
tipo, su línea y la entrada a la que pertenece la línea (document, data, filled,
un fichero de estilos...):
{"kind": "INVALID_DOCUMENT", "code": "JSON_NOT_VALID", "line": 2, "source": "data", "message": "..."}
Línea de comandos
Los comandos del jar tienen los nombres de las rutas:
| Comando | Qué hace |
|---|---|
start |
Arranca el servicio HTTP con su server.stxt |
render <documento> -o <fichero> |
Convierte un documento a PDF, con --styles, --data, --pdf-ua, --pdf-a... |
print <plantilla> -o <fichero> |
Convierte una plantilla de la carpeta de plantillas |
documents <documento> -o <fichero> |
Convierte un documento de la carpeta de documentos |
fill <documento> --data <fichero> |
Escribe el documento con sus Slots rellenos |
Desde la raíz del repositorio, con la factura de arriba:
java -jar server/stxt-press.jar fill factura.stxt --data factura.json
java -jar server/stxt-press.jar render factura.stxt --data factura.json -o factura.pdf --config server/server.stxt
Un error se escribe en stderr con su fichero y su línea:
stxt-press: factura.stxt:15: SLOT_NO_DATA: Node 'Paragraph': No data for ${cliente}
El código de salida es 0 si el trabajo termina bien, 1 si falla (el documento, sus
datos, un recurso, un límite) y 2 si la invocación no es válida. Un fichero de -o
solo se sustituye si el trabajo termina bien.
Configuración
Un servidor se configura con un fichero server.stxt, validado con el esquema
dev.stxt.press del jar:
Server (dev.stxt.press):
Host: 0.0.0.0
Port: 8080
Token env: STXT_PRESS_TOKEN
Resource folder: resources
Template folder: templates
Document folder: documents
Routes:
Render: false
Save: true
Limits:
Timeout: 20
Max pages: 500Sin fichero, el servidor escucha en 127.0.0.1:8080, sin token y sin plantillas ni
documentos. Las rutas relativas lo son a la carpeta de server.stxt. Todos los nodos
están en el README.
Seguridad
El servidor no tiene TLS ni usuarios: está pensado para ir detrás de un proxy inverso que los añada.
- Token: con
Token env, todas las rutas salvo/healthy las páginas pidenAuthorization: Bearer <token>. - Nombres locales: sin token y en una dirección local, solo responde a peticiones
cuyo
Hostes local, contra el DNS rebinding. - Rutas apagadas:
Render: false,Files: falseyEditor: falseenRoutesdejan solo la impresión de las plantillas y los documentos.
Versiones
Los dos proyectos están en 0.x. Hasta la 1.0, el namespace dev.stxt.pdf, la API Java,
las rutas y server.stxt pueden cambiar entre versiones menores, y el PDF de un
documento válido también. Cada cambio está en el CHANGELOG.md de su repositorio.