STXT, prosa dentro de la estructura

CMS y validación de la estructura

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.

STXT con Markdown

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.

Y la plantilla que valida estructura y cardinalidad:

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

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:

# 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**.

Frontmatter

---
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.

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.

MDX

---
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.

<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>

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.

Markdoc

---
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 %}

El esquema es un objeto JavaScript. Declara las etiquetas, sus atributos y qué hijos aceptan:

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);

La cardinalidad no es declarativa, y el documento se mezcla con código en otro lenguaje.

YAML con 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.
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.

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.

KDL

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.
                """
        }
    }
}

Un extracto del esquema, escrito también en KDL:

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" } }
                }
            }
        }
    }
}

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.

Este portal

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.