Proyecto HIVEWEB
Post anterior: Entendiendo cómo funciona el generador de sitios web HUGO
Página web: ahiveweb.com
Post No.- 3 - Fundamentos y primeros pasos.
¡Hola amigos! En este post doy una explicación detallada de cada uno de los pasos que he seguido para armar la primera HIVEWEB, desde la instalación del "framework" para el CSS, el uso de "HUGO Pipes", y la construcción del template baseof.html para todo el sitio y del template index.html para la "home page", terminando con el uso de servidor web de HUGO para visualizar la primera página HIVEWEB. Espero que les agrade el post.
Para construir un sitio web con el generador HUGO lo primero que debemos tener es un "Tema" (theme) instalado. Hay dos opciones para el "Tema"; o lo instalamos desde alguno de los repositorios o proveedores de la lista de temas para HUGO, o lo construimos nosotros mismos. En nuestro caso, que estamos experimentando en la construcción de un sitio web con contenido que se encuentra en la cadena de bloques de HIVE, la mejor opción por ahora es crear nuestro propio "Tema". De esta manera podemos personalizar al máximo las características y funcionalidades de nuestro sitio web, adaptándolo apropiadamente a las particularidades de esos contenidos.
Requisitos para construir un "Tema"
Un "Tema" es un conjunto de templates que obtienen datos, variables y funciones desde los front matter de archivos Markdown, que luego son procesados por HUGO para crear la estructura y diseño del sitio web. Los templates se construyen básicamente con código HTML, CSS y funciones del lenguage de programación golang.
El CSS para nuestro TEMA
Para el CSS vamos a utilizar un "framework" para agilizar el desarrollo del diseño del sitio web. El "framework" que voy a utilizar es BULMA porque no se requieren grandes conocimientos de CSS para poder utilizarlo, además es "open source", tiene muchos componentes listos para usar y es altamente responsive.
BULMA es una librería de CSS. Esto significa que proporciona clases de CSS que se utilizan para diseñar y decorar el código HTML. Hay dos opciones para usar BULMA; se puede usar el archivo .css precompilado o instalar los archivos .sass para personalizarlo acorde con nuestras necesidades.
EL archivo precompilado .css de BULMA
Para utilizar el archivo precompilado de BULMA tenemos varias opciones. La primera opción es descargarlo directamente desde el sitio de BULMA y copiarlo en nuestro sitio web, y la segunda opción es utilizarlo directamente desde los CDN (content delivery network).
Si descargamos el archivo para guardarlo en nuestro sitio web, entonces debemos utilizar el siguiente código HTML en la sección head de nuestro sitio:
<link rel="stylesheet" href="https://tusitioweb.com/directorio_donde_esta/bulma.min.css">
Si utilizamos un CDN, el código es el siguiente:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.3/css/bulma.min.css">
El archivo precompilado y comprimido de BULMA tiene un tamaño aproximado de unos 21 KB. Es un archivo relativamente pequeño tomando en cuenta que tiene todas las clases CSS del "framework" BULMA, se estén utilizando o no en el sitio web. Dentro de las prioridades del proyecto HIVEWEB se encuentran mantener al mínimo posible el consumo de recursos de los usuarios que visiten el sitio web, y garantizar páginas web rápidas y seguras. El tiempo que se tarda en cargar y leer los archivos de estilos o CSS de las páginas web, es uno de los parámetros fundamentales que determinan la rapidez de respuesta de un sitio web. De hecho toda la carga del sitio web se detiene hasta que se complete la carga de los archivos CSS.
Cargar los archivos desde el propio sitio web tiene algunas ventajas y desventajas. La principal ventaja es que siempre está disponible el archivo si el servidor web está funcionando adecuadamente; de esta manera el sitio no depende de que los servicios de terceros estén funcionando adecuadamente, como es el caso de los CDN. La desventaja de no utilizar un CDN es que nuestro servidor tiene que trabajar un poco más para servir dichos archivos y consumir ancho de banda propio. La ventaja de usar un CDN es que es altamente probable que los usuarios ya tengan en la cache de su navegador el archivo precargado, lo que hace que la carga de la página web sea mucho más rápido que la que podemos ofrecer cargando directamente desde nuestro sitio web.
En cualquier caso siempre es recomendable reducir al mínimo el tamaño del archivo CSS, y para ello hay que eliminar de dicho archivo todas aquellas clases que no se utilicen en nuestro sitio web. Para poder hacer esta reducción tenemos que crear nuestro propio CSS a partir de la librería de BULMA, y ésto se logra trabajando directamente con los archivos .sass o scss.
Utilizando los archivos sass y scss de BULMA
Los archivos .sass (Syntactically Awesome StyleSheets) y .scss (Sassy CSS) son archivos con sintaxis avanzada para construir el archivo CSS de un sitio web. Para poder construir los archivos CSS a partir de estos archivos .sass o .scss se requiere tener instalado un preprocesador de CSS. BULMA tiene su propio preprocesador y puede ser instalado utilizando npm (Node Package Manager).
La ventaja de utilizar los archivos .sass o .scss es que las clases de CSS vienen agrupadas por tipo de objeto que se quiere construir para el sitio web. Por ejemplo, en un archivo se tienen todo lo relacionado con el decorado de tablas, y si el sitio web no requiere del uso de tablas, entonces dichas clases no tienen porque ser incluidas en el archivo CSS final. Esto permite crear archivos CSS con el tamaño mínimo necesario para construir todo el sitio, sin tener clases de CSS que no se utilicen en la construcción del sitio. El resultado es que se pueden obtener archivos CSS comprimidos que no llegan a 1 KB, acelerando dramáticamente la rapidez con la que se cargan nuestras páginas web.
Cuando se utilizan archivos .sass o .scss uno puede alterar el valor de las variables que se utilizan para construir el archivo CSS, lo cual otorga una gran flexibilidad a la hora de diseñar nuestro sitio web. BULMA ofrece en su sitio web todas las variables que pueden ser cambiadas en los archivos .sass y .scss, haciendo extremandamente fácil y rápido la adaptación de colores, esquemas y de todos sus componentes.
El procesamiento de scss y scss en HUGO
HUGO tiene un sistema de procesamiento de recursos en secuencia, el cual se denomina "HUGO Pipes". Básicamente, HUGO puede procesar subrutinas, procesos funciones, etc, de manera secuencial; donde los datos de salida del proceso anterior funcionan como datos de entrada del siguiente proceso. Una de las tantas ventajas de "HUGO Pipes" es que permite el procesamiento de archivos tipo .sass y .scss. Ésto significa que no es necesario instalar el preprocesador de CSS de BULMA, ya que cualquier archivo sass o scss se puede transformar en un archivo CSS directamente en HUGO usando el comando resources.ToCSS que toma dos argumentos, el objeto de recurso y un mapa de opciones. El código necesario para hacer ésto se muestra a continuación:
{{ $sass := resources.Get "sass/main.scss" }}
{{ $style := $sass | resources.ToCSS }}
Como vemos, lo que se hace es definir una variable $sass en la que se ha guardado el contenido del archivo main.scss que se encuentra en el directorio sass. Este directorio sass para que pueda ser procesado por el comando resources debe estar ubicado en un directorio llamado assets. El directorio assets puede estar ubicado en el directorio raiz del "Tema" o en el directorio raiz del proyecto HUGO, junto a los directorios content,data, etc.
En el segundo comando se define la hoja de estilo CSS, que se ha creado con el nombre de variable $style. El simbolo "|" es la aplicación de "HUGO Pipes" en la que se hace el preprocesamiento del archivo $sass y se transforma en CSS con el comando resources.ToCSS. Esto es todo lo que se necesita para crear un archivo CSS en HUGO a partir de los archivos scss o scss.
Instalando el CSS para nuestra HIVEWEB
Ahora estamos listos para comenzar a crear nuestro "Tema" para nuestra HIVEWEB. Lo primero que tenemos que hacer es darle un nombre a nuestro "Tema", que para el proyecto HIVEWEB he decidido llamarlo con el mismo nombre pero en minúsculas, es decir, el "Tema" se llamará hiveweb. Espero que esto no cause ningún tipo de confusión. Para ello, debemos crear un directorio con el nombre hiveweb en el directorio themes. Creamos este directorio usando el comando mkdir de Ubuntu en el directorio raiz del proyecto:
mkdir /themes/hiveweb
Para poder utilizar el preprocesador de CSS de HUGO debemos crear un directorio llamado assets en el directorio del "Tema" hiveweb. Volvemos a utilizar mkdir:
mkdir /themes/hiveweb/assets
Ahora lo que debemos hacer es bajar todos los archivos de sass del repositorio de BULMA y guardarlos en nuestro directorio assets de nuestro "Tema". El repositorio es bastante grande, tiene un tamaño cercano a los 100 MB, y el directorio sass tiene apenas unos 75 KB, y es el único directorio que necesitamos para trabajar en HUGO. Por tanto, sólo voy a descargar dicho directorio usando el paquete de Ubuntu svn (software de subversión). Si no tienes instalado svn lo puedes hacer con el siguiente comando:
sudo apt install subversion
Ahora para descarga sólo el directorio sass del repositorio de BULMA de su rama principal utilizamos los siguientes comandos:
svn checkout https://github.com/jgthms/bulma/trunk/sass
Luego de unos segundos se habrá descargado sólo el directorio de sass. Lo importante a destacar aquí es como se construye la URL del directorio que se quiere descargar, ya que se debe dar la URL principal del repositorio seguido de /trunk/ y luego el nombre del directorio que se va a descargar. "trunk" indica a github que estamos interesados en la rama master o main del repositorio.
Ya con esto tenemos todas las clases CSS que podemos llegar a necesitar para construir nuestro sitio web. Si optamos por utilizar el archivo precompilado de BULMA simplemente todos los archivos que se muestran en la siguiente imágen son cargados, pero con el preprocesador tenemos la opción de sólo cargar el archivo que necesitamos.
Construyendo el template para la home page
Bien, seguimos con la construcción nuestro "Tema hiveweb". Lo que debemos hacer ahora es crear nuevos directorios en el directorio /themes/hiveweb que son el directorio layouts y el directorio static. Dentro del directorio layouts creamos los directorios _default, partials y shorcodes. Para ello usamos el comando mkdir desde la raiz de nuestro proyecto:
mkdir themes/hiveweb/static
mkdir themes/hiveweb/layouts
mkdir themes/hiveweb/layouts/partials
mkdir themes/hiveweb/layouts/shorcodes
mkdir themes/hiveweb/layouts/_default
El primer template que debemos crear es el denominado baseof.html. El contenido de este template lo he tomado del sitio web de HUGO y es el siguiente:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{ block "title" . }}
{{ .Site.Title }}
{{ end }}</title>
</head>
<body>
{{ block "main" . }}
{{ end }}
{{ block "footer" . }}
{{ end }}
</body>
</html>
Este archivo debe guardarse como baseof.html en el directorio /themes/hiveweb/layouts/_default.
¿Qué es baseof.html?
El template baseof.html es la base para todos los códigos HTML del sitio web. Todas las páginas web construidas tendrán la estructura que se defina en este template.
La estructura definida en este ejemplo de template es muy básica, pero nos servirá para ir introduciendo cada uno de los elementos y códigos que necesitamos para armar nuestra HIVEWEB.
Como vemos el template tiene una sección <head> donde se define el metadado del tipo de formato de codificación de caracteres Unicode (ISO 10646) denominado utf-8. Además define el metadato title para nuestra página web, utilizando el comando {{block "title" . }}, que le da la instrucción al template de introducir todo el código que se defina bajo el término title, este comando block siempre se debe cerrar con {{end}}. El comando {{.Site.Title}} corresponde a la variable title definida en el config.toml del proyecto HUGO, es decir introduce el nombre que le hayamos dado a nuestro proyecto en el archivo de configuración.
En la sección <body> de nuestro HTML se definen dos bloques adicionales que son el "main" y el "footer", y como en el caso anterior, introducen todos los comandos que se definan en esos bloques de código.
Definiendo el template de nuestra home page
Ahora vamos a construir el template para nuestra "home page". Este archivo debe tener el nombre de index.html y debe guardarse en el directorio themes/hiveweb/layouts/index.html. Ésto es así porque HUGO tiene reglas estrictas para ubicar los archivos y el orden de prioridad de esos archivos. Esas prioridades las discutiremos más adelante en los próximos artículos.
En nuestro baseof.html se han definido tres bloques que son el bloque del título en el <head> y los bloques main y footer en el <body>. Pues, nuestro template para la "home page" o para cualquier otra página, tienen que definir esos bloques para que se pueda construir la página web. En el caso de nuestra "home page" definimos por ahora esos bloques de la siguiente manera:
{{ define "title" }}
{{ .Title }} – {{ .Site.Title }}
{{ end }}
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
{{ define "footer" }}
<h1>Pié de página</h1>
<p>Aquí colocaríamos algo al final...</p>
{{ end }}
Como vemos los bloques se definen con el comando {{ define "nombre_del_blque"}} ... {{end}}, dentro de los cuales se coloca el código HTML o de Go que necesitamos ejecutar.
Ya tenemos el template para nuestro "home page", ahora sólo queda definir el archivo del contenido de nuestro "home page".
El contenido de nuestro "home page"
Ya sabemos que HUGO funciona tomando el contenido de un archivo Markdown y procesándolo a través de una serie de templates para construir una página web. Ya tenemos el template para la "home page", pero no tenemos aún el archivo Markdown de esa "home page".
El archivo Markdown de la "home page" se debe llamar _index.md y debe estar ubicado en la raiz del directorio content. Vamos a crear ese archivo Markdown con el siguiente contenido:
---
title: "EL NUEVO TITULO DE NUESTRA HOME PAGE"
date: 2021-06-30
draft: True
---
# ¡HOLA MUNDO!
Nuestra primera versión de Home PAGE
¡Listo! Ya tenemos todos los elementos necesarios para construir nuestra "home page"; hemos construido el template para la "home page" y el archivo Markdown _index.md con el contenido de nuestra "home page", ahora a construir nuestro sitio.
Construyendo el sitio HIVEWEB
Antes de poder construir nuestro sitio web tenemos que crear o editar nuestro archivo de configuración config.toml con el siguiente contenido:
baseURL = "https://ahiveweb.com/"
languageCode = "es-ve"
title = "HIVEWEB: Una página web para cada usuario de HIVE"
theme="hiveweb"
Para construir nuestro sitio web debemos utilizar un servidor web. HUGO tiene su propio servidor web y este se activa utilizando el comando hugo server -D, con lo cual se obtendrá el resultado que se muestra en la siguiente imágen:
HUGO procesará los archivos Markdown que se encuentran en el directorio content, que en nuestro caso por ahora sólo es la "home page", con los templates de nuesro "Tema hiveweb". El servidor nos arroja dos advertencias sobre que no tenemos los templates para las taxonomías, lo cual es cierto porque aún no la hemos construido, podemos ignorar eso por ahora. Lo importante es que nuestra página web la podemos ver en: Web Server is available at http://localhost:1313/ (bind address 127.0.0.1). Abrimos en nuestro navegador y ya tenemos nuestra página web tal como se muestra en la siguiente imágen:
Como pueden notar es una página muy básica porque aún no hemos agregado la decoración a través del CSS, lo cual haremos en la próxima publicación.
La estructura que vemos en nuestra página web es la estructura que hemos definido en el template baseof.html. Como se trata de la "home page" la información para rellenar el template baseof.html la ha tomado del template index.html, y el contenido de index.html lo ha tomado del archivo Markdown _index.md.
Hasta aquí lo dejo en esta publicación. En el próximo artículo comenzaremos a crear una estructura más ideal para nuestro sitio web, introduciendo el CSS y creando los metadatos, partials y otros templates para nuestro sitio web.
Espero que les haya gustado el "post", y no duden en hacer cualquier pregunta y sobre todo agradezco sus comentarios.
Saludos.