xfarch.org — Sitio de documentación

Sitio estático multi-idioma para la especificación de referencia del Modelo de Arquitectura Cross-Framework (CFAM). Las páginas de especificación se generan automáticamente a partir de fuentes LaTeX mediante pandoc; la página de inicio y los assets son ficheros estáticos mantenidos manualmente.

---

Estructura del proyecto

docs/
├── index.html                  # Página de inicio (landing page estática)
├── .nojekyll                   # Deshabilita el procesado Jekyll en GitHub Pages
├── Makefile                    # Automatización de la generación
│
├── assets/
│   ├── css/
│   │   └── style.css           # Hoja de estilos global (tema, tipografía, layout)
│   ├── js/
│   │   └── docs.js             # Interactividad: scroll-spy, toggle mobile, anclas
│   └── pandoc-template.html    # Plantilla HTML para pandoc (cabecera, sidebar, footer)
│
├── es/
│   └── index.html              # Especificación completa en español (generada)
├── en/
│   └── index.html              # Placeholder — traducción en curso
└── cat/
    └── index.html              # Placeholder — traducció en curs

Ficheros generados vs. ficheros manuales

Fichero	Origen	Modificar manualmente
es/index.html	Generado por pandoc	❌ Se sobreescribe con make es
en/index.html	Placeholder manual	✅ Hasta que haya fuente LaTeX EN
cat/index.html	Placeholder manual	✅ Hasta que haya fuente LaTeX CAT
index.html	Manual	✅
assets/css/style.css	Manual	✅
assets/js/docs.js	Manual	✅
assets/pandoc-template.html	Manual	✅

---

Generación del sitio

Prerrequisitos

# macOS
brew install pandoc

# Ubuntu / Debian
sudo apt install pandoc

Comandos disponibles

# Generar todos los idiomas disponibles
make

# Generar sólo la versión española
make es

# Eliminar ficheros generados
make clean

Flujo de generación (make es)

xfa-es.tex  →  pandoc  →  es/index.html
                 │
                 ├── --from=latex+raw_tex     Parsea LaTeX extendido
                 ├── --to=html5               Produce HTML5 semántico
                 ├── --standalone             Documento completo (no fragmento)
                 ├── --toc --toc-depth=3      Tabla de contenidos hasta nivel 3
                 ├── --number-sections        Numeración automática de secciones
                 ├── --section-divs           Cada sección en un <section> con id
                 ├── --mathjax                Renderizado de fórmulas con MathJax
                 ├── --highlight-style=breezedark  Highlighting de bloques de código
                 └── --template=assets/pandoc-template.html

Tras la generación, el Makefile aplica un parche automático sobre el HTML producido:

sed -i 's|/usr/share/javascript/mathjax/...|https://cdn.jsdelivr.net/...|g' es/index.html

Este sed corrige la ruta local de MathJax que pandoc inserta en entornos Linux para usar la CDN pública de jsdelivr, necesaria en producción.

---

Plantilla pandoc (assets/pandoc-template.html)

La plantilla define el chrome del sitio (cabecera, sidebar, footer) y actúa de envolvente para el contenido generado. pandoc sustituye las variables de plantilla en tiempo de generación:

Variable	Contenido
$body$	HTML del cuerpo del documento (generado desde LaTeX)
$toc$	Árbol de navegación <nav> con todos los anclajes
$lang$	Código de idioma (es, en, cat)
$title$	Título del documento
$math$	Bloque <script> de MathJax (si el documento contiene fórmulas)

La plantilla no debe modificarse para cambiar el aspecto visual del contenido. Todo el estilo se controla exclusivamente desde assets/css/style.css.

---

Estilos (assets/css/style.css)

El fichero de estilos sigue una arquitectura de dos familias tipográficas:

• --font-ui (Inter) — cabecera, navegación lateral, badges, footer.
• --font-content (CMU Serif / Computer Modern) — cuerpo del documento, tabla de contenidos lateral, fórmulas de texto.
• --font-mono-inline (CMU Typewriter Text) — código inline dentro del cuerpo.
• --font-mono-block (JetBrains Mono) — bloques de código fuente.

Las clases HTML que pandoc genera y que el CSS referencia son:

Clase pandoc	Significado
section.level1 … section.level4	Sección numerada por profundidad
section.unnumbered	Sección sin número (ej. \subsection*{})
.header-section-number	Span con el número de sección (1.2.3)
.toc-section-number	Número en la entrada de TOC del sidebar
.sourceCode	Bloque de código fuente
.math.inline / .math.display	Fórmula LaTeX inline o en bloque
tr.odd / tr.even	Filas alternas de tabla

---

JavaScript (assets/js/docs.js)

El script se inicializa en DOMContentLoaded y gestiona cuatro comportamientos:

• initMobile() — Toggle del sidebar en viewport estrecho (botón hamburguesa).
• initScrollSpy() — IntersectionObserver sobre los headings del contenido; resalta el enlace activo en el sidebar TOC según la posición de scroll.
• initAnchorCopy() — Click en cualquier h2/h3 copia la URL con el ancla de esa sección al portapapeles.
• initLangHighlight() — Marca como active el enlace de idioma que corresponde a la URL actual.

---

GitHub Pages

El sitio se publica directamente desde la carpeta docs/ de la rama principal. El fichero .nojekyll evita que GitHub Pages intente procesar el contenido con Jekyll, lo que causaría que los paths con guiones bajos quedaran excluidos.

Para publicar una nueva versión de la especificación basta con ejecutar make es localmente, hacer commit de es/index.html y hacer push.