Códice | Entradas sobre «ssg»

Blogeando...

JavGuerra — Thu, 21 Apr 2022 00:00:00 GMT

Etiquetas: #código, #markdown, #jekill, #ssg

Hola Mundo. Primera entrada del blog.

Nota: Esta entrada hace referencia a la versión inicial de este blog realizado con Jekill. El repositorio de esa versión del blog es: blog.

Gracias a Jekill, un Generador de Sitios Estáticos (SSG) y Github pages, hoy ve la luz este blog para volcar en él apuntes de interés sobre los temas que me apasionan.

Lo he llamado «códice» por su similitud con un conjunto de hojas sueltas cosidas entre si, como eran los libros antes de la encuadernación.

El tema gráfico empleado en este blog es Beautiful Jekyll del que hice fork traduje al español y cambié algunas configuraciones para empezar.

Si quieres crear tu propio blog, en su repositorio tienes las indicaciones necesarias para instalar todo.

Usando Sergey SSG

JavGuerra — Fri, 26 Aug 2022 00:00:00 GMT

Etiquetas: #web, #html, #node.js, #ssg, #herramienta

«Si alguna has hecho un cambio en cada encabezado en un sitio web totalmente estático, sabrás lo engorroso y propenso a errores que es copiar y pegar los cambios en todos los ficheros. Ahí es donde entra en juego Sergey. Sergey le permite mover ese encabezado a un único fichero que se puede importar y te ayuda a incluirlo donde lo necesites.»

Así describe el autor de esta herramienta la funcionalidad de su Generador de Sitios Estáticos. Se trata de una utilidad simple que permite hacer importaciones de código en nuestro HTML empleando Node.js para generar la página resultante.

La página de ejemplo

En esta entrada voy a mostrar un ejemplo práctico. Cómo usar Sergey SSG en la web de una iniciativa sobre tarjetas de emergencia para enfermedades raras o poco frecuentes.

Hay una serie de requisitos funcionales y operativos por los que se ha optado por la creación de una página estática:

Rápida. La página debe cargar lo más rápido posible para que pueda ser accedida incluso en entornos donde hay poco ancho de banda, ya que la información médica que contiene debe estar disponible en cualquier lugar de Latinoamérica, por este motivo, debe pesar poco para un consumo bajo de ancho de banda y no usar procesos como la consulta a BBDD que retrasen su carga.
Mantenible. La página debe poder actualizarse con rapidez y sin gran esfuerzo.

Se optó por desarrollar la página sin usar ningún CMS ni base de datos de respaldo, empleando sólo HTML + CSS. Para la maquetación se usó Bootstrap, simplificando el desarrollo y su posterior mantenimiento, y las zonas comunes de las páginas web fueron extraídas para ser insertadas como slots, en cada página HTML. Esto permite que para hacer cambios en estos contenidos repetidos sólo sea necesario modificar un fichero, y el resto de páginas mostrarán los cambios.

Sergey SSG

Todos los generadores de sitios estáticos funcionan de forma análoga. Toman una serie de páginas codificadas de una forma concreta y las convierten a HTML que puede ser usado en un navegador. lo que los diferencia es el código que incluyen estas páginas para generar el resultado que deseamos.

Ya que el propósito de esta entrada no es hacer una revisión de la herramienta, te dejo enlace a un video de Jonathan MirCha sobre sus características y uso básico paso a paso.

LiveCoding Primeros pasos con Sergey un SSG minimalista

La instalación y uso de Sergey SSG requiere tener instalado Node.js.

Ver las indicaciones de instalación en: https://sergey.trysmudford.com/

Importaciones

La página de ejemplo consta de una HTML principal o portada y de él derivan todas las otras páginas estáticas de la web. Todas ellas tienen la misma estructura:

Inicio, con la información del head de la página.
Cabecera de la página, con el logo y el título de la página. (En algunos casos contiene más de un logo)
Cuerpo de la página. Este es el contenido que cambia en cada página.
Fin, o pie de página.

Inicio, cabecera y fin son los contenidos que se repiten y no cambian, si bien en ellos, como veremos, hay información específica de cada página.

Lo que necesito es que cada página web estática contenga el cuerpo de la página, es decir la información propia y específica de esa página, pero que las otras partes de la página que tienen una estructura repetida se inserten en la página desde otro fichero.

Por alguna razón, HTML no implementa esta característica que si tienen CSS y JavaScript, y aunque en su momento se intentó llevar a cabo, no cuajó. Ver info sobre Imports HTML.

Según parece, hay un estándar en ciernes llamado HTML módulos que permitiría importar HTML como si fuesen módulos de Javascript mediante import. Para saber más: HTML Modules Explainer

Hasta que se estandarice, Sergey SSG es una razonable alternativa.

Vamos por partes

…dijo el descuartizador de Boston. Este mal chiste da pie a entender cómo vamos a trabajar.

Cada parte susceptible de repetirse en las distintas páginas se sacará, a una carpeta llamada _imports, y estos documentos «importables» serán referenciados en cada una de las páginas donde se utilicen.

Para conocer las etiquetas de importación de Sergey SSG, puedes visitar la sección Slots de su página.

Las partes que vamos a reutilizar son:

inicio.html
cabecera.html
cabecera-multiple.html
fin.html

1. Inicio

Este fichero contiene el head de la página, y el comienzo del body:

<!DOCTYPE html>
<html lang="es" prefix="og: http://ogp.me/ns# website: http://ogp.me/ns/website#">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title><sergey-slot name="title" /></title>
    <meta name="description" content="<sergey-slot name="description" />" />
    <meta name="author" content="Javier Guerra" />
    <meta name="license" content="CC-BY Conectiva.Lat" />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:site" content="@conectiva_lat" />
    <meta property="og:url" content="https://conectiva.lat/emergencias/index.html" />
    <meta property="og:type" content="website" />
    <meta property="og:title" content="Tarjetas de emergencia" />
    <meta property="og:description" content="Descargar las tarjetas de emergencia para Enfermedades Poco Frecuentes." />
    <meta property="og:image" content="https://conectiva.lat/emergencias/assets/banner.png" />
    <meta property="og:image:type" content="image/png" />
    <meta property="og:image:width" content="1024" />
    <meta property="og:image:height" content="512" />
    <meta property="og:image:alt" content="Banner" />
    <meta property="og:locale" content="es_ES" />
    <link rel="manifest" href="https://conectiva.lat/emergencias/manifest.json" />
    <link rel="shortcut icon" href="<sergey-slot name="assets" />assets/favicon.png" />
    <link rel="stylesheet" href="<sergey-slot name="assets" />assets/estilos.css" />
    <sergey-slot />
</head>

<body>
    <div class="container">

Como se aprecia, hay una serie de etiquetas sergey-slot en este fichero. Para entenderlo mejor, tenemos que ver cómo se inserta este fichero en las páginas.

<sergey-import src="inicio">
    <sergey-template name="title">Tarjetas de Emergencia</sergey-template>
    <sergey-template name="description">Descargar las tarjetas de emergencia para Enfermedades Poco Frecuentes.</sergey-template>
</sergey-import>

Estas son las líneas que uso en el fichero index.html para insertar la cabecera de la página.

Vemos aquí un <sergey-import src="inicio"> que indica cual es el import que voy a insertar, que en este caso se llama inicio (inicio.html), y una serie de etiquetas sergey-template con información que debe ir en la cabecera que voy a importar. Esta información será distinta en cada HTML, pero no así el resto de contenido de la cabecera que está en el fichero externo. Con estos sergey-template indico qué datos deben sustituirse en el import genérico allí donde aparezca una etiqueta sergey-slot en inicio.html, consiguiendo de esta forma tener un fichero externo, común a todas las páginas que lo incluyan, donde puedo hacer cambios de forma sencilla que afectarán a todas esas páginas, pero sin perder la funcionalidad de la personalización de algunos aspectos de cada página, como por ejemplo el titulo…

Con este import definimos el title de la página, la description y puedo añadir contenido en este caso al final de head si lo deseo, como he hecho con el script dentro del sergey-import, ya que en el fichero inicio.html he colocado un <sergey-slot /> justo antes de la etiqueta de cierre de la cabecera.

En este caso no incluyo templates para los <sergey-slot name="assets" /> en inicio.html porque no los necesito, pero cuando uso este import en ficheros que están dentro de subcarpetas, si debo indicar sus rutas, pudiendo añadir entonces:

<sergey-template name="assets">../</sergey-template>

para indicar así que estoy en una subcarpeta, añadiendo ../ al inicio de la ruta de assets/favicon.png y assets/estilos.css, que ahora serán ../assets/favicon.png y ../assets/estilos.css respectivamente, alcanzando sin errores los contenidos ubicados en la carpeta assets. Como vimos en el fichero inicio.html, los slot para estas rutas serían:

<link rel="shortcut icon" href="<sergey-slot name="assets" />assets/favicon.png" />
<link rel="stylesheet" href="<sergey-slot name="assets" />assets/estilos.css" />

No importa usar comillas dobles dentro de comillas dobles, ya que Sergey SSG se encargará de sustituir <sergey-slot name="assets" /> por ../ en el fichero final resultante.

{: .box-note} Nota: Cuando en el fichero de importación incluyo un <sergey-slot /> pero no le envío contenido, Sergey SSG crea un salto de línea no deseado. Cuando hacemos un import de contenido que está tabulado, Sergey tabula la primera línea del contenido que incluye en <sergey-slot /> correctamente, pero no hace lo mismo con el resto de líneas, que no conservan el tabulado original. Si eres un obseso de la tabulación de tus líneas de código tienes un problema. He abierto una Issue para que estas cuestiones puedan ser corregidas en la siguiente versión, si esta llega a ver la luz. Por lo demás, el software funciona correctamente y hace su función.

2. Cabecera

La cabecera contiene el logo, el título y subtítulo. El código es:

<header>
    <div class="row">
        <div class="col-sm order-sm-last text-end">
            <a href="https://conectiva.lat" target="_blank">
                <img src="<sergey-slot name="assets" />assets/conectiva-logo.svg" width="148" alt="Logo de Conectiva" />
            </a>
        </div>
        <div class="col-sm">
            <h1><sergey-slot name="h1" /></h1>
            <h2><sergey-slot name="h2" /></h2>
        </div>
    </div>
</header>

<a href="#contenido" class="visually-hidden-focusable">Ir a los recursos</a>

que es llamado desde el HTML con:

<sergey-import src="cabecera">
    <sergey-template name="h1">Tarjetas de emergencia</sergey-template>
    <sergey-template name="h2">Enfermedades Poco&nbsp;Frecuentes</sergey-template>
</sergey-import>

En este caso se trata del código incluido en el fichero index.html. si se tratase de un fichero en una subcarpeta, deberíamos incluir los _template_ de la ruta del logo. Por ejemplo:

<sergey-import src="cabecera">
    <sergey-template name="h1">Tarjeta de emergencias</sergey-template>
    <sergey-template name="h2">Síndrome de Loeys-Dietz</sergey-template>
    <sergey-template name="assets">../</sergey-template>
</sergey-import>

Como en inicio.html, el import trae el fichero, en este caso cabecera.html, y lo inserta en el html rellenando las etiquetas slots con el contenido especificado en las etiquetas template.

3. Cabecera múltiple

En algunas páginas, como ocurre aquí, la cabeceras incluye dos logos. El código del import en este caso es:

<header>
    <div class="row">
        <div class="col-sm order-sm-last text-end">
            <ul class="enLinea">
                <sergey-slot />
                <li>
                    <a href="https://conectiva.lat" target="_blank">
                            <img src="<sergey-slot name="assets" />assets/conectiva-logo.svg" width="148" alt="Logo de Conectiva" />
                    </a>
                </li>
            </ul>
        </div>
        <div class="col-sm">
            <h1><sergey-slot name="h1" /></h1>
            <h2><sergey-slot name="h2" /></h2>
        </div>
    </div>
</header>

<a href="#contenido" class="visually-hidden-focusable">Ir a los recursos</a>

que no se diferencia mucho de la cabecera simple, si no es por la inclusión de un <sergey-slot /> y de la lista ordenada que va a incluir los distintos logos. Este import será llamado desde las páginas con el código:

<sergey-import src="cabecera-multiple">
    <sergey-template name="h1">Tarjeta de emergencias</sergey-template>
    <sergey-template name="h2">Síndrome Ehlers-Danlos</sergey-template>
    <sergey-template name="assets">../../</sergey-template>
    <li>
        <a href="https://www.facebook.com/ACOEDCR" target="_blank">
            <img src="../../assets/acoed.svg" width="150" alt="Logo ACOED" />
        </a>
    </li>
</sergey-import>

Como se aprecia, no es necesario seguir el mismo orden de los slots para definir los template.

4. Fin

En el fichero fin.html defino el pie y el cierre de página:

        <footer>
            <div class="row">
                <div class="nota">
                    <div class="d-flex">
                        <div class="ms-3 me-3">
                            <i class="bi bi-info-circle"></i>
                        </div>
                        <div>
                            <p>
                                <small>Las <a href="https://conectiva.lat/emergencias/index.html">tarjetas de
                                    emergencia</a> son una iniciativa abierta y gratuita del equipo de trabajo de
                                    Emergencias de <a href="https://conectiva.lat" target="_blank">Conectiva</a> para
                                    las personas afectadas por Enfermedades Raras, Huérfanas o Poco Frecuentes.</small>
                            </p>
                        </div>
                    </div>
                </div>
            </div>
        </footer>

    </div>
</body>

</html>

En este caso no uso ningún slot, por lo que el código para importarlo es muy simple:

<sergey-import src="fin" />

Imagina la de cosas que se pueden hacer con esta forma de trabajar. Incluir por ejemplo un banner donde quieras en tu página y poder cambiarlo según las circunstancias, extraer partes de la página para hacerla modular, menús, secciones, etc.

Una página completa

Una vez vista cada importación por partes, veamos cómo quedaría el index.html:

<sergey-import src="inicio">
    <sergey-template name="title">Tarjetas de Emergencia</sergey-template>
    <sergey-template name="description">Descargar las tarjetas de emergencia para Enfermedades Poco Frecuentes.</sergey-template>
</sergey-import>

<sergey-import src="cabecera">
    <sergey-template name="h1">Tarjetas de emergencia</sergey-template>
    <sergey-template name="h2">Enfermedades Poco&nbsp;Frecuentes</sergey-template>
</sergey-import>


<!-- Aquí el código HTML de nuestra página -->


<sergey-import src="fin" />

Al generar la página con npm start a partir de este código, se mostraría lo siguiente:

<!DOCTYPE html>
<html lang="es" prefix="og: http://ogp.me/ns# website: http://ogp.me/ns/website#">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Tarjetas de Emergencia</title>
    <meta name="description" content="Descargar las tarjetas de emergencia para Enfermedades Poco Frecuentes." />
    <meta name="author" content="Javier Guerra" />
    <meta name="license" content="CC-BY Conectiva.Lat" />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:site" content="@conectiva_lat" />
    <meta property="og:url" content="https://conectiva.lat/emergencias/index.html" />
    <meta property="og:type" content="website" />
    <meta property="og:title" content="Tarjetas de emergencia" />
    <meta property="og:description" content="Descargar las tarjetas de emergencia para Enfermedades Poco Frecuentes." />
    <meta property="og:image" content="https://conectiva.lat/emergencias/assets/banner.png" />
    <meta property="og:image:type" content="image/png" />
    <meta property="og:image:width" content="1024" />
    <meta property="og:image:height" content="512" />
    <meta property="og:image:alt" content="Banner" />
    <meta property="og:locale" content="es_ES" />
    <link rel="manifest" href="https://conectiva.lat/emergencias/manifest.json" />
    <link rel="shortcut icon" href="assets/favicon.png" />
    <link rel="stylesheet" href="assets/estilos.css" />
</head>

<body>
    <div class="container">

        <header>
            <div class="row">
                <div class="col-sm order-sm-last text-end">
                    <a href="https://conectiva.lat" target="_blank">
                        <img src="assets/conectiva-logo.svg" width="148" alt="Logo de Conectiva" />
                    </a>
                </div>
                <div class="col-sm">
                    <h1>Tarjetas de emergencia</h1>
                    <h2>Enfermedades Poco&nbsp;Frecuentes</h2>
                </div>
            </div>
        </header>

        <a href="#contenido" class="visually-hidden-focusable">Ir a los recursos</a>


<!-- Aquí el código HTML de nuestra página -->


        <footer>
            <div class="row">
                <div class="nota">
                    <div class="d-flex">
                        <div class="ms-3 me-3">
                            <i class="bi bi-info-circle"></i>
                        </div>
                        <div>
                            <p>
                                <small>Las <a href="https://conectiva.lat/emergencias/index.html">tarjetas de
                                    emergencia</a> son una iniciativa abierta y gratuita del equipo de trabajo de
                                    Emergencias de <a href="https://conectiva.lat" target="_blank">Conectiva</a> para
                                    las personas afectadas por Enfermedades Raras, Huérfanas o Poco Frecuentes.</small>
                            </p>
                        </div>
                    </div>
                </div>
            </div>
        </footer>

    </div>
</body>

</html>

Los ficheros generados resultantes, ya como páginas estáticas con todo su contenido, estarán en la carpeta public, y serán estos ficheros los que podremos subir a nuestro servidor.

Más opciones en Sergey SSG

Sergey SSG tiene un par de opciones más interesantes.

Puede gestionar enlaces con sergey-link, algo muy útil cuando queremos mostrar a los usuarios dónde se encuentran dentro de la página.

Sergey SSG también puede importar texto en formato Markdown como se indica aquí.

Si intentas visualizar los cambios de las páginas que estás creando antes de generar tus ficheros estáticos, estos se mostrarán con errores, ya que el código de Sergey SSG no es reconocido por el navegador. Te recomiendo que revises las distintas opciones para ejecutar Sergey SSG e incluso para tener una previsualización de los cambios que vas realizando en tiempo real.

Enlaces

Ir a la página de las tarjetas de emergencia
Generadores de sitios estáticos
Sergey SSG
Repositorio de Sergey SSG en GitHub
LiveCoding Primeros pasos con Sergey un SSG minimalista - Video
PostHTML Static Site Starter - Alternativa
Mini SSG - Alternativa
Eleventy - Alternativa popular

Códice

JavGuerra — Wed, 21 Aug 2024 00:00:00 GMT

Etiquetas: #portfolio, #web, #código, #astro, #ssg, #tailwind, #javascript, #typescript, #zod, #node.js, #markdown, #responsive, #accesibilidad

Hacia tiempo que quería darle un giro a mi anterior git-blog elaborado con Jekill. Hace un mes me topé con Astro, un SSG en JavaScript/TypeScript bajo Node.js, que cuenta con una excelente documentación, y que además incluye un tutorial para hacer un blog. Esto terminó de decidirme para realizar el cambio que ahora presento.

Retos

Para llevar a cabo el desarrollo de un nuevo blog personalizado, se me presentaban dos retos:

Realizar la aplicación para que fuera operativa al menos con la mayoría de funcionalidades que ya tenía en el anterior blog.
Migrar las entradas del blog anterior a la nueva estructura de la aplicación, lo que además implicaba repensar esta estructura.

La aplicación

Elaborar la aplicación fue realmente sencillo. Siempre hay atascos, pero con la documentación, el tutorial, el Discord de Astro, los videos de YouTube y la IA, fueron subsanándose. El proyecto ha sido el mejor aprendizaje posible.

Tres cosas me han llevado algo de tiempo:

Extender la colección de posts usando el esquema RSS.
Utilizar el componente «Image» de Astro.
JavaScript/TypeScript no funciona como se espera usando transiciones.

Lo relativo a la colección es lógico, porque estaba usando conceptos nuevos y aprendiendo a usar la biblioteca Zod para definir y validar el esquema de los datos de las colección de entradas del blog. Zod permite validar el frontmatter o cabecera de cada post para que no falte nada. La idea era partir del esquema rssSchema y extenderlo para que incluyese algunos datos no contemplados, como por ejemplo el coverImage o los tags (Ver fichero /src/content/config.ts).

Pero confieso que el uso del componente Image me ha dado algún quebradero de cabeza, posiblemente relacionado con el schema mencionado, pues no me ha sido posible usar indistintamente imágenes con rutas relativas o rutas absolutas en los encabezados de las entradas. El problema tiene que ver con el atributo src.

Si bien Image permite indicar una ruta relativa (/public) o remota (https), cuando se trata de usar la carpeta /src/assets surgen los problemas. La solución pasa por importar las imágenes, pero ¿qué ocurre cuando se ha de importar una colección de imágenes, para, por ejemplo, el listado de los proyectos del portafolio?

Mi opción consiste en crear un arreglo con todas las imágenes importadas usando import.meta.glob(), y luego acceder a cada elemento del arreglo referenciado por su ruta, como se muestra aquí:

---
import portfolio from "@/content/_portfolio.json";  // proyectos con sus respectivas rutas de imagenes
const images = import.meta.glob("@/assets/portfolio/*", { eager: true });

const projects = portfolio.projects.map(project => {
  const image = images[`/src/assets/portfolio/${project.img}`] as Record<string, any>;
  return { ...project, image }; // a cada proyecto se le añade la imagen importada
---

projects.map(project => 
  <Image src={project.image.default} alt={project.alt} inferSize />
)

Este ejemplo simplificado mostrará la lista de imágenes asociadas a los proyectos.

La migración

Versión previa del blog en Jekill

Tras conseguir que todo funcionase, llegó el turno de la migración, que pensaba que sería complicada, pero sólo fue laboriosa.

Haciendo uso del filtrado de contenido del IDE fui cambiando los enlaces de Jekill de las referencias entre las distintas entradas, y creando el nuevo encabezado (frontmatter) de cada entrada escrita en Markdown.

A medida que este cambio se iba realizando fue necesario ir adaptando los estilos de texto haciendo uso de Tailwind y su plugin Typography.

Por último, como decidí incluir las transiciones de Astro, me topé con un problema curioso. Para activar o desactivar el menú hamburguesa uso JavaScript. La primera vez que se usa, funciona, pero en los siguientes casos, deja de hacerlo. Lo mismo ocurre con el botón «Volver».

He tenido que hacer una comprobación para recargar siempre el evento click en ambos casos. Ver /src/components/Hamburger.astro y /src/components/ButtonLink.astro respectivamente.

Lo mejor de todo es que ha sido divertido hacerlo, y conocer Astro, esta nueva y muy potente herramienta que creo que va a dar mucho juego. Quedan por delante innumerables mejoras y actualizaciones, por lo que la diversión continúa.

Características

La aplicación cuenta con las siguientes secciones: portada, sobre mi, porfolio, blog, temas y enlaces recomendados. Hace uso de las características avanzadas de Astro, y también:

Incluye RSS de contenidos
Enlaza con la API de Mastodon
Implementa sitemap para SEO
Incluye estadísticas del sitio
Integra Disqus para comentarios
Implementa un buscador
Usa tema de color claro/oscuro automático
Realiza transiciones de página
Es accesible
Es responsive
Usa TypeScript
Contiene etiquetado Open Graph
Es compatible con PWA
Consigue una calificación de carbono «A» (ver)