Document (dev.stxt.website): STXT: prosa dentro de la estructura Metadata: Last modif: 2026-09-24 Description: STXT inserta la prosa en la estructura. La misma lección en Markdown con Frontmatter, MDX, Markdoc, YAML y STXT: dónde va la estructura y qué valida cada uno. Header: @STXT@, prosa dentro de la estructura Assert >> Frontmatter, MDX y Markdoc insertan la estructura en la prosa. @STXT@ inserta la prosa en la estructura, y así **se puede validar el documento completo**. Subheader: CMS y validación de la estructura Content >> Cuando un documento necesita prosa, habitualmente se usa Markdown. El problema aparece cuando también necesita una estructura que debe validarse. La solución habitual consiste en insertar la estructura **dentro** de Markdown, usando otro lenguaje. La mayoría de las veces esto permite una validación parcial, pero con soluciones que se parecen más a un hack que a una respuesta estructural. El coste es el siguiente: - Más lenguajes en juego - Más complejidad de escritura para personas no técnicas - Menos legibilidad general - Entornos menos uniformes - Mezcla de texto con código En este artículo mostramos cómo @STXT@ invierte la solución: inserta la prosa dentro de una estructura que puede validarse. Mostramos un mismo documento, una `Lección` con una estructura concreta, y cómo se valida con las distintas soluciones actuales. También lo mostramos en YAML y en KDL, dos formatos que sí admiten la prosa dentro de la estructura, aunque no es habitual encontrarlos en un CMS. Subheader: @STXT@ con Markdown Code >> Lección (com.example.school.es): ¿Qué es STXT? Autores: Autor: Joan Costa Autor: James Smith Docente: Sheila Jones Dificultad: fácil Introducción >> STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. Contenido >> Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. Pregunta: ¿Qué otro formato es parecido? Respuesta: XML, por ejemplo Contenido >> Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. Conclusión >> Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. Cuestionario: Pregunta: ¿Cómo se expresa la estructura de un documento? Respuesta >> Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. Pregunta: ¿Qué pasa con el texto de un bloque `>>`? Respuesta >> Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. Content >> Y la plantilla que valida estructura y cardinalidad: Code >> Template (@stxt.template): com.example.school.es Structure >> Lección: Autores: (1) Autor: (+) Docente: (1) Dificultad: (?) ENUM [fácil, media, difícil] Introducción: (?) MARKDOWN Contenido: (*) MARKDOWN Pregunta: (*) Respuesta: (1) MARKDOWN Conclusión: (?) MARKDOWN Cuestionario: (?) GROUP Pregunta: (+) @Pregunta Content >> Todo el documento se puede validar con la plantilla: estructura, cardinalidad y contenido. En la prosa no hace falta ningún carácter de escape. Un documento con errores no valida: Code >> # ERROR: este documento no valida Lección (com.example.school.es): ¿Qué es STXT? Autores: Autor: Joan Costa # Falta `Docente` # `trivial` no es una dificultad de la lista Dificultad: trivial Introducción >> STXT es un **formato de texto jerárquico**. Subheader: Frontmatter Markdown >> --- tipo: lección título: ¿Qué es STXT? autores: - Joan Costa - James Smith docente: Sheila Jones dificultad: fácil --- # Introducción STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. # Contenido Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. **Pregunta**: ¿Qué otro formato es parecido? **Respuesta**: XML, por ejemplo # Contenido Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. # Conclusión Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. # Cuestionario ## ¿Cómo se expresa la estructura de un documento? Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. ## ¿Qué pasa con el texto de un bloque `>>`? Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. Content >> La pregunta, la respuesta y el cuestionario son una convención, y nada comprueba esa estructura. El Frontmatter se puede validar con un esquema externo: JSON Schema, o un esquema Zod en las colecciones de contenido de Astro. Subheader: MDX Markdown >> --- tipo: lección título: ¿Qué es STXT? autores: - Joan Costa - James Smith docente: Sheila Jones dificultad: fácil --- import { Pregunta, Cuestionario } from '../components/Leccion' # Introducción STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. # Contenido Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. XML, por ejemplo # Contenido Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. # Conclusión Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. Content >> `Pregunta` y `Cuestionario` son componentes JavaScript definidos en otro fichero. El documento se compila a un módulo JavaScript, mezclando el documento con código. En la prosa, `<` y `{` abren JSX y expresiones, así que hay que escaparlos. Subheader: Markdoc Markdown >> --- tipo: lección título: ¿Qué es STXT? autores: - Joan Costa - James Smith docente: Sheila Jones dificultad: fácil --- # Introducción STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. # Contenido Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. {% pregunta texto="¿Qué otro formato es parecido?" %} XML, por ejemplo {% /pregunta %} # Contenido Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. # Conclusión Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. {% cuestionario %} {% pregunta texto="¿Cómo se expresa la estructura de un documento?" %} Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. {% /pregunta %} {% pregunta texto="¿Qué pasa con el texto de un bloque `>>`?" %} Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. {% /pregunta %} {% /cuestionario %} Content >> El esquema es un objeto JavaScript. Declara las etiquetas, sus atributos y qué hijos aceptan: TypeScript >> const config = { tags: { pregunta: { render: 'Pregunta', attributes: { texto: { type: String, required: true }, }, }, cuestionario: { render: 'Cuestionario', children: ['tag'], }, }, }; const ast = Markdoc.parse(source); const errors = Markdoc.validate(ast, config); Content >> La cardinalidad no es declarativa, y el documento se mezcla con código en otro lenguaje. Subheader: YAML con Markdown Yaml >> tipo: lección título: ¿Qué es STXT? autores: - Joan Costa - James Smith docente: Sheila Jones dificultad: fácil introducción: | STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. cuerpo: - contenido: | Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. - pregunta: ¿Qué otro formato es parecido? respuesta: XML, por ejemplo - contenido: | Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. conclusión: | Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. cuestionario: - pregunta: ¿Cómo se expresa la estructura de un documento? respuesta: | Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. - pregunta: ¿Qué pasa con el texto de un bloque `>>`? respuesta: | Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. Content >> Aquí la prosa está dentro de la estructura, como en @STXT@, con una diferencia importante: En **YAML** las claves son únicas, así que los elementos repetidos tienen que ir en una lista (artificial). Esto hace que visualmente sea más difícil distinguir si el carácter `-` pertenece a los nodos de la estructura o es contenido de la prosa. En @STXT@ la repetición es natural y no hace falta ninguna lista: todo es una estructura de nodos de texto. Assert >> El **modelo mental** de YAML y @STXT@ es muy distinto al escribir contenido en un CMS. YAML se parece más a JSON: hay mapas y listas. @STXT@ se parece más a XML, con árboles de texto. Subheader: KDL Listing >> lección "¿Qué es STXT?" { autores { autor "Joan Costa" autor "James Smith" } docente "Sheila Jones" dificultad "fácil" introducción """ STXT es un **formato de texto jerárquico**: fácil de leer para las personas y trivial de parsear para las máquinas. """ contenido """ Un documento es un árbol de nodos. Solo hay dos tipos: - `Nombre: valor`, para valores cortos en línea. - `Nombre >>`, para un bloque de texto literal, como este. La indentación *es* la estructura: sin etiquetas de cierre, sin comillas y sin caracteres de escape. """ pregunta "¿Qué otro formato es parecido?" { respuesta "XML, por ejemplo" } contenido """ Los comentarios son las líneas que empiezan por `#`. Los documentos pueden tener namespaces. Se declaran con `Nombre (namespace.nombre)`. """ conclusión """ Con dos tipos de nodo y la indentación se puede describir cualquier documento. Una plantilla añade **validación**, sin cambiar la sintaxis. """ cuestionario { pregunta "¿Cómo se expresa la estructura de un documento?" { respuesta """ Con la indentación: un nodo es hijo del nodo anterior más cercano que tiene un nivel menos. """ } pregunta "¿Qué pasa con el texto de un bloque `>>`?" { respuesta """ Se conserva literalmente. No se interpreta nada de su interior. Puede ser Markdown, código o cualquier otro texto. """ } } } Content >> Un extracto del esquema, escrito también en KDL: Listing >> document { node "lección" { min 1 max 1 value { type "string" } children { node "docente" { min 1; max 1; value { type "string" } } node "dificultad" { max 1; value { enum "fácil" "media" "difícil" } } node "contenido" { value { type "string" } } node "pregunta" { value { type "string" } children { node "respuesta" { min 1; max 1; value { type "string" } } } } } } } Content >> KDL es el formato más parecido a @STXT@ de esta página: nodos con nombre, ordenados, que se repiten y tienen hijos. Las diferencias están en la sintaxis. Igual que en YAML, es más difícil distinguir visualmente los distintos componentes. Los valores van entre comillas, y en la prosa `\` es un carácter de escape. Subheader: Este portal Content >> Cada página de `stxt.dev` es un documento @STXT@ con la prosa en Markdown. Se puede añadir `.stxt` a la dirección de cualquier página para ver el código fuente, por ejemplo [stxt-vs-markdown.stxt](stxt-vs-markdown.stxt).