Guía del sitio SCavanna.com

El sitio usa Jekyll para convertir Markdown y plantillas en HTML estático. GitHub Actions compila ese HTML y GitHub Pages lo publica en el dominio configurado en CNAME; no necesita una base de datos ni un servidor de aplicaciones.

Estructura principal

index.md: portada.
_pages/: páginas, artículos, ensayos permanentes e índices de cada tema; conserva aquí también sus documentos y medios.
_posts/: artículos cronológicos, con fecha en el nombre del archivo.
_data/menu.yml: temas y subtemas de la portada y de «Explorar».
_data/series.yml: orden y enlaces de las series de lectura.
_layouts/ y _includes/: plantillas compartidas.
assets/css/site.css y assets/js/: diseño, tema y búsqueda.
scripts/ y tests/: copia de recursos y validaciones del sitio generado.
_config.yml: dominio, metadatos y plugins de Jekyll.

Agregar una página, artículo o ensayo

Para contenido organizado por tema y que debe permanecer en un lugar estable, crea una carpeta bajo _pages/. Por ejemplo:

_pages/
  Seguridad-IA/
    index.md
    agentes/
      index.md
      identidad-de-agentes.md
      imagenes/
      presentacion.pptx
      video.mp4

Cada index.md funciona como portada o índice de esa carpeta. Enlaza desde ella a los artículos y recursos que contiene. Define un permalink explícito, en minúsculas y con guiones, para que la URL no dependa del nombre de archivo:

---
layout: page
title: "Identidad de los agentes"
description: "Principios para proteger las identidades no humanas."
permalink: /seguridad-ia/agentes/identidad/
date: 2026-04-22
modified: 2026-04-22
tags: [Seguridad, Microsoft]
---

## Primera sección

Contenido en Markdown.

La plantilla ya muestra el título como encabezado principal; comienza el cuerpo con ## para evitar repetirlo. Conserva el permalink una vez publicado. Si necesitas cambiar una URL, agrega la anterior en redirect_from y comprueba los enlaces.

Para publicar un ensayo con fecha y que aparezca en el feed cronológico, crea _posts/AAAA-MM-DD-titulo.md. Por ejemplo, _posts/2026-04-22-seguridad-de-agentes.md, con layout: post, title, date, description y tags en el front matter. Los posts también se incluyen en la búsqueda y en los feeds. Si el ensayo pertenece a una sección temática permanente, usa _pages/ y enlázalo desde su índice.

Agregar o destacar una sección

Crea _pages/<seccion>/index.md con su title, description y permalink: /<seccion>/.
Agrega la sección a _data/menu.yml, usando ese mismo URL. Añade featured: true si también debe aparecer en la portada; agrega elementos a submenu para mostrar subtemas en la navegación.
Crea carpetas y páginas para los subtemas bajo _pages/<seccion>/. Añade sus enlaces a la página índice de la sección y, si corresponde, a submenu.
Usa nombres simples, preferentemente en minúsculas y sin espacios ni acentos, para los archivos enlazados. Las rutas publicadas distinguen mayúsculas de minúsculas.

Para incluir un artículo en una serie, agrega series: clave-de-la-serie al encabezado y añade su título y permalink a _data/series.yml, en el orden de lectura. Edita _data/menu.yml para cambiar los temas, sus descripciones y sus subtemas; featured: true los muestra también en la portada.

Imágenes, documentos y videos

Guarda los recursos propios de un artículo junto a él dentro de _pages/; así la carpeta mantiene juntos el texto y sus archivos. Por ejemplo, _pages/Seguridad-IA/agentes/identidad-de-agentes.md puede enlazar /Seguridad-IA/agentes/presentacion.pptx. Para imágenes reutilizadas en distintas páginas o en el diseño del sitio, usa assets/images/ y proporciona texto alternativo descriptivo. Si existe una versión liviana, usa image_preview para la visualización y image para el original.

El script scripts/copy-collection-assets.mjs copia desde _pages/ al sitio generado los archivos .pdf, .pptx, imágenes .png, .jpg, .jpeg, .gif, .webp, .svg y videos .mp4, .webm, .mov, .m4v, conservando carpetas y nombres. Por ejemplo, _pages/Seguridad-IA/agentes/guia.pdf se publica en /Seguridad-IA/agentes/guia.pdf. En Markdown puedes enlazar un archivo con [Descargar la presentación](/Seguridad-IA/agentes/presentacion.pptx).

Los navegadores no suelen mostrar un .pptx directamente: ofrece un enlace de descarga. Para incluir un video pequeño en una página, usa HTML:

<video controls preload="metadata" playsinline>
  <source src="/Seguridad-IA/agentes/video.mp4" type="video/mp4">
  Tu navegador no puede reproducir este video.
</video>

Los videos pueden hacer crecer mucho el repositorio y la descarga de la página. Para videos grandes, es mejor alojarlos en una plataforma de video y enlazarlos o insertarlos desde allí; añade al repositorio solo imágenes de vista previa y documentos ligeros.

Compilar y comprobar localmente

Requisitos: Ruby con Bundler, Node.js 18 o posterior y, para el servidor de ejemplo, Python 3. Desde la raíz del repositorio, después de editar contenido, ejecuta:

bundle install
bundle exec jekyll build
node scripts/copy-collection-assets.mjs
node scripts/check-site.mjs
node --test tests/site.test.mjs
python -m http.server 4000 --directory _site

Abre http://localhost:4000 para revisar la versión generada. Si vuelves a cambiar archivos, detén el servidor, repite los comandos de compilación, copia y validación y luego inícialo otra vez. No edites _site/ directamente: se vuelve a generar.

El comprobador verifica enlaces y recursos internos, incluyendo mayúsculas, secciones de páginas, el índice de búsqueda y las URLs del sitemap y del feed. El flujo de GitHub Actions ejecuta estas mismas validaciones antes de publicar.

Búsqueda, feeds y publicación

La búsqueda genera search-index.json durante la compilación y se ejecuta en el navegador; no envía las consultas a un servicio externo. Las páginas de relleno TBD y los README de secciones no se incluyen en el índice.

El sitemap se genera con jekyll-sitemap. Los feeds Atom y JSON incluyen artículos de _pages/ y _posts/ que tengan una fecha date; los artículos sin fecha siguen siendo navegables y se pueden encontrar mediante la búsqueda.

Al subir cambios a la rama main, .github/workflows/pages.yml compila el sitio, copia los recursos de _pages/, ejecuta las validaciones y, si todo pasa, despliega el resultado en GitHub Pages. Por tanto, el ciclo habitual es: editar o añadir archivos, ejecutar las validaciones locales, hacer commit y subir a main; no hay que modificar _site/ ni ejecutar un script de publicación aparte.