Anatomía de una página

Objetivo principal: que cualquiera que escriba una página del manual produzca la misma estructura, y que cualquiera que lea una sepa dónde encontrar cada cosa sin buscarla.

Esta página describe el formato, no una pantalla de la plataforma. Es la única del portal que habla del portal.

Las cuatro partes, en este orden

Una página de vista tiene cuatro partes. El orden no es negociable: es lo que permite que quien ha leído una sepa leer todas.

#	Parte	Qué contiene	Qué NO va aquí
1	Objetivo principal	Una frase: para qué sirve esa pantalla	Cómo está implementada
2	📸 Mapeo de interfaz	La captura real, con los elementos numerados dentro de la imagen	Maquetas, montajes o recortes de otra versión sin avisar
3	🧩 Despiece de elementos	Una fila por número de la imagen	Elementos que la captura no muestra, con número inventado
4	💡 Guía de uso	Cuándo se usa, qué esperar, y qué no hace	Repetir el despiece con otras palabras

Si el objetivo no cabe en una frase, la página está describiendo dos pantallas y hay que partirla.

El despiece

Cinco columnas, y la cabecera se escribe siempre igual:

| # | Nombre del elemento | Tipo | Destino / Acción | Descripción funcional |

La columna Tipo dice qué clase de control es —botón, enlace, campo, tabla, aviso—, y Destino / Acción dice a dónde lleva o qué dispara. Un elemento que no lleva a ninguna parte y no dispara nada lleva una raya, no una descripción repetida.

Los números están pintados dentro del PNG

Es la consecuencia menos evidente de todo esto y la que más daño hace si se ignora. Los recuadros numerados forman parte de la imagen. Por eso, en una página que sí tiene captura:

• nunca se renumera una fila ni se reordena la tabla;

• nunca se añade una fila con un número que la imagen no muestre;

• un elemento real que la captura no señala se añade al final de la tabla con una raya en la columna del número, y se escribe una vez, encima de la tabla:

  Los elementos marcados con — no aparecen señalados en la captura: existen en la plataforma pero la imagen no los numera.

Renumerar la tabla la desalinea de la imagen en silencio: nada falla, y el lector que busca el 4 encuentra otro elemento. Por eso scripts/check_manual.py falla si aparece una fila con raya y no está la línea que la explica.

Las dos variantes, y solo dos

Página sin captura. Una pantalla real puede no estar fotografiada todavía. En ese caso no se inventa una imagen ni se deja el hueco en silencio: se sustituye el mapeo de interfaz por este aviso, y el despiece pierde la columna del número porque no hay imagen sobre la que numerar. Quedan cuatro columnas.

:::info[Todavía sin captura]
Esta página describe una pantalla que aún no está fotografiada, así que el despiece no numera los
elementos sobre una imagen. Lo que se cuenta aquí está contrastado con la plataforma desplegada.
:::

Captura de una versión anterior. Cuando la plataforma ha avanzado más allá de lo que muestra la imagen, el texto se pone al día y se advierte en el punto donde afecta, nunca al final:

:::note[La captura no muestra esto]
La imagen corresponde a una versión anterior. Hoy esta pantalla incluye además …
:::

La regla que gobierna las dos: el texto describe la plataforma de hoy, y donde la imagen no lo respalde, se dice. Un lector no debe encontrarse nunca una contradicción entre lo que lee y lo que ve sin que la página se la explique.

Lo que rompe el portal si se incumple

Un solo H1 por página. Las secciones van en ##. El índice lateral arranca en H2: una sección escrita con # no aparece en él.

El title del front matter dice lo mismo que el H1. El title es lo que se ve en la pestaña del navegador, en las migas y en el buscador; el H1, lo que se lee en la página. Cuando se separan, el lector busca una cosa y encuentra otra.

Imágenes en sintaxis markdown, nunca <img>. Solo se convierten en recursos del sitio las rutas escritas como ![alt](./fichero.png). Un <img src="./x.png"> compila sin protestar y da una imagen rota en producción.

La imagen vive junto a su página. Nada de URLs externas ni de adjuntos efímeros: se rompen y además exigen autenticación.

Ningún dato de alumnado real. El portal es público aunque el repositorio no lo sea. Ni identificadores de cuenta reales, ni correos de dominio real, ni direcciones de red del centro.

Y aquí hay una vuelta de tuerca que conviene entender, porque no es evidente: un identificador real de un centro y uno inventado son indistinguibles por su forma. Los dos son una letra, un guion y unas cifras. No hay patrón que separe uno del otro.

Así que se invierte el problema. El manual reserva a-000NN —de a-00000 a a-00099— para los ejemplos, y la comprobación rechaza cualquier otro identificador con esa forma, esté en prosa o dentro de un bloque de código. Un identificador real no puede colarse sin saltarse una regla explícita.

Esta página no puede ni poner un contraejemplo

Escribir aquí un identificador fuera del rango, aunque fuera solo para enseñar cuál se rechaza, hace fallar la comprobación. Ocurrió al redactar esta misma página. Es incómodo y es la prueba de que la regla no tiene puerta trasera: no hay marca de «este es un ejemplo, déjalo pasar», porque esa marca sería exactamente por donde se colaría un dato real.

Los correos de ejemplo van a @ejemplo.com. Las únicas direcciones de red admitidas son 127.0.0.1 y 0.0.0.0, que son las que el propio manual manda escribir.

Un | dentro de `código` también separa celdas. Es la regla de Markdown que menos se espera y la que más daño hace, porque no rompe el build: la tabla se renderiza con celdas de más y el sobrante se recorta en silencio. Dentro de una tabla hay que escribirlo \|.

Antes de dar por buena una página

python scripts/check_manual.py

Sale con código 1 si algo falla y dice qué. Es la misma comprobación que corre en CI, así que si pasa aquí, pasa allí. Y mientras escribes, un hook valida cada página al guardarla: no hace falta acordarse de ejecutarlo.