Para muestra un botón, este blog fue creado en una tarde utilizando estas herramientas. Hugo como generador de contenido estático, PaperMod como plantilla, Netlify como almacenaje web y manejador de contenido. Se requiere también un servidor git, que para efectos de este breve tutorial será GitHub.

Este tutorial está dirigido a aquellas personas que se inician en la administración o programación de computadoras.

Si usas Windows te recomiendo que, en cuanto a la terminal de línea de comandos, uses PowerShell, ya que la consola tradicional de Windows podría no ser compatible con el formato de comandos que usamos aquí.

Instalación de Hugo y Git

Hugo es un generador de sitios web estáticos (sólo html, hojas de estilo y javascript para el lado del cliente). Programado en Go, su sistema de plantillas también está basado en ese lenguaje, pero no te preocupes, no requerirás conocerlo en estos momentos.

Hugo usará la plantilla para transformar archivos de texto con tu contenido markdown en páginas html, también se encargará de generar los índices, enlaces de navegación interna del sitio y hasta el archivo RSS para que otros enlacen a lo más reciente de tu blog.

Hugo es un programa que se ejecuta en una terminal de comandos. Te recomiendo que sigas las instrucciones de instalación en su propio sitio web de acuerdo al sistema operativo que estés usando.

Ya que estás instalando programas, también instala Git, es un sistema distribuido de control de versiones que nos servirá para llevar un control de cambios de nuestro proyecto y permitirá conectar nuestro almacén de código local con un servidor git remoto (más adelante tendrá sentido esto).

Creación de proyecto Hugo

Una vez instalado Hugo y Git en tu computadora, comenzaremos creando un proyecto.

1
2
3

$ mkdir blog
$ hugo new site blog -f "yaml"
$ cd blog

Ya que estamos aquí, iniciaremos un depósito git para que siga los cambios en el código del proyecto.

1

$ git init

Antes de comenzar a editar archivos, necesitaremos agregar la plantilla a nuestro proyecto.

Instalación de PaperMod

PaperMod es una excelente plantilla para Hugo desarrollada por Aditya Telange, quien propone tres metodos para agregar la plantilla. Yo te voy a recomendar el método 2: ordenaremos a Git que agregue la plantilla como un submodulo de tu proyecto, de este modo, cuando el desarrollador de la plantilla haga una mejora en el código, puedes usar al propio Git para obtener los cambios y a Hugo para regenerar todo tu blog.

1

$ git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

Listo, Git ahora controla tu proyecto, y dentro de él, hay un submódulo o subproyecto, la plantilla PaperMod. Este subproyecto está “enlazado” al control de cambios del desarrollador original de la plantilla, pero el código está copiado dentro de tu proyecto.

Ahora sí vamos a comenzar a editar archivos. Puedes usar un programa llamado Visual Studio Code aunque cualquier otro editor de archivos de texto te puede funcionar.

Configuración de Hugo

Primero modificaremos el archivo ‘blog/config.yml’. Puedes sobrescribir el contenido con la siguiente guía. Personaliza tu nombre y mensaje de bienvenida.

El fragmento de texto ‘urldemiblog.com’ se repite dentro del archivo, ese no lo cambies todavía (salvo que ya tengas un nombre de dominio seleccionado), ya que usaremos uno que nos proporcionará Netlify más adelante.

Netlify CMS

A continuación prepararemos lo necesario para usar a Netlify como manejador de contenidos, lo que nos permitirá subir nuevas entradas al blog.

Para la interfaz administrativas, crearemos una carpeta y dos archivos dentro de ella.

1
2

$ cd static
$ mkdir admin

Usa tu editor de texto para crear dos archivos dentro de esa carpeta, llamados ‘index.html’ y ‘config.yml’. Los contenidos los puedes copiar desde aquí:

Nota: Este archivo de configuración deberás guardarlo bajo el nombre ‘config.yml’ en ‘blog/static/admin/config.yml’ (no ‘admin_config.yml’, ese nombre solo fue para guardarlo en el Gist).

Ahora, para funcionar correctamente, Netlify CMS requerirá que unas líneas de código sean insertadas en ciertas partes de los archivos generados por Hugo con base en la plantilla PaperMod.

PaperMod está formado por fragmentos de código que Hugo ensambla para construir páginas web. Nosotros no vamos a editar las plantillas de PaperMod ya que Git, como controlador de cambios, está gestionando ese código como un submódulo enlazado al repositorio original de su autor. Ni vamos a enviarle nuestros cambios personales al autor, ni queremos que se vayan a sobrescribir nuestros cambios cuando actualicemos el submódulo si el autor original hace mejoras a PaperMod.

Vamos a usar unos ’layouts’ o fragmentos que PaperMod le indica a Hugo que busque en nuestro código para complementarse.

En la carpeta ‘blog/themes/PaperMod/layouts/partials’ están los fragmentos que Hugo ensamblará para formar las páginas web estáticas. Esos no los tocaremos, en cambio crearemos archivos ‘heredados’ similares en nuestro propio proyecto para complementarlos.

Nos ubicaremos de nuevo en la carpeta ‘blog’, si estamos todavía en ‘blog/static/admin’, haremos lo siguiente:

1

$ cd ..\..

Ahora crearemos un carpeta ‘blog/layouts/partials’ y colocaremos dos archivos allí dentro (’extend_footer.html’ y ’extend_head.html’):

1
2

$ cd layouts
$ mkdir partials

Por último, agregaremos un archivo ‘arquetipo’, que es una plantilla que usará el manejador de contenidos para crear cada nueva publicación de nuestro blog. En la carpeta ‘blog/archetypes’, crearemos el archivo ‘post.md’ y su contenido lo puedes obtener aquí:

Repositorio remoto con GitHub

Ya tenemos el código necesario. Ahora configuraremos algo de infraestructura externa. Hugo genera contenidos estáticos con base en la plantilla y archivos de texto en formato markdown con tus artículos. Pero estos archivos son generados y almacenados solo en tu computadora, queremos que tu blog esté visible para todo mundo.

Vamos a usar Git para que suba una copia de tu proyecto Hugo a un repositorio remoto en un servicio llamado GitHub (hay otros también, pero este tutorial se limitará a ayudarte a configurar ese en específico).

Esa copia de tu proyecto almacenada en GitHub, va a ser monitoreada por Netlify para que cuando le cambies algo o le agregues algo nuevo, ejecutará su propia versión de Hugo para generar tu sitio web en línea otra vez y actualizarlo para que todo mundo vea los cambios.

Crea una cuenta y repositorio en GitHub

Crea una cuenta en GitHub si no tienes una ya, sigue las instrucciones que allí mismo te indican.

Cuando tengas confirmada tu cuenta, crea un nuevo repositorio. Puedes llamarlo ‘mi-blog’ y seleccionar ‘Private’ para que sólo tú lo puedas ver.

Configura el repositorio local

Vamos a configurar nuestro repositorio local para que apunte al repositorio remoto que acabamos de crear en GitHub. Si todavía estamos en la carpeta ‘blog/layouts/partials’, haremos lo siguiente:

1

$ cd ..\..

Ahora daremos unas instrucciones a Git, suponiendo que en GitHub llamaste a tu repositorio ‘mi-blog’ y para el nombre de usuario cambia ‘minombre’:

1
2

$ git remote add origin git@github.com:minombre/mi-blog.git
$ git branch -M main

Ahora tenemos algo que llamamos ‘rama principal’ llamada ‘main’ y hemos apuntado nuestro repositorio local al repositorio remoto que acabos de crear en GitHub.

Esta parte es algo complicada, pero no imposible de realizar. Tenemos que obtener unas credenciales en GitHub, para que nuestro Git local pueda enviarle los archivos de nuestro proyecto.

Obtener email en GitHub para identificar envíos

En GitHub ve a la configuración de perfil. De la columna de la izquierda, selecciona la pestaña ‘Emails’, busca la opción ‘Keep my email addresses private’ y actívala. En ese mismo espacio, el texto te explica que los envíos de código a GitHub deberán llevar como remitente una dirección de correo falsa que allí te indican, del tipo ‘183745+minombre+users.noreply.github.com’. Copia ese email falso porque vamos a usarlo para identificarnos desde nuestro Git local.

Configurar nombre y email en Git local

De nuevo en nuestra terminal de comandos (Usa el correo falso que obtuviste en GitHub y pon tu nombre o nickname):

1
2

$ git config --global user.email "183745+minombre+users.noreply.github.com"
$ git config --global user.name "mi nombre"

Para comprobar que todo esté en orden:

1
2

$ git config --global user.email
$ git config --global user.name

Eso debería mostrar los datos actualizados que recién configuraste.

Actualizar control de cambios local

Vamos a ordenar a Git tomar como agregado y realizado todos los archivos y cambios que hemos hecho hasta ahora en nuestro proyecto.

1
2
3

$ git add .
$ git commit -m "Primer commit"
$ git status

Ese último comando debe informarte que no hay nada más pendiente y que el árbol de trabajo está limpio. Ahora vamos a crear unas llaves en GitHub.

Crear firma digital

Puedes consultar los detalles de cómo generar una llave SSH aquí. En breve, las instrucciones son las que a continuación describo.

Generar una llave SSH nueva

Las llaves SSH sirven para autenticar una conexión entre dos computadoras. Consiste de dos archivos, uno que contiene una llave privada y otro que contiene una llave pública.

Abrimos la aplicación ‘Git Bash’ que debió instalarse junto con Git.

Introducimos los siguientes comandos en la terminal Git Bash. Como email usaremos el obtenido en GitHub.

1

$ ssh-keygen -t ed25519 -C "183745+minombre+users.noreply.github.com"

Primero se preguntará por el nombre y ubicación del archivo para guardar llave. Si no tienes motivo especial para elegir otra ruta que la que sugiere por defecto, sólo presiona ENTER.

Después te va a solicitar una contraseña. Es importante que proporciones una que no olvides o que no hayas anotado en algún lugar que puedas perder. Al finalizar presiona ENTER. Se te pedirá que vuelvas a escribir la contraseña, hazlo para confirmar y presiona ENTER.

Agregar la llave SSH al agente de control de llaves local

Nos aseguraremos de que el agente local esté funcionando correctamente. En la misma terminal Git Bash:

1

$ eval "$(ssh-agent -s)"

Debería mostrar un mensaje que diga algo como ‘Agent pid 1648’, si es así, todo está en orden.

Ahora agregaremos al agente la clave SSH que recién generamos. Te solicitará la contraseña de la llave.

1

$ ssh-add ~/.ssh/id_ed25519

Informar a GitHub nuestra firma digital pública

Ya casi concluimos con las llaves. Tenemos que dar a conocer a GitHub la versión pública de nuestra llave, para que cuando realicemos envío de código, reconozca ese envío como nuestro. Usaremos la página de GitHub para ello.

Vamos a copiar la llave pública al portapapeles, después la pegaremos en un formulario de la página web de GitHub.

1

$ clip < ~/.ssh/id_ed25519.pub

Ahora abre la sección ‘SSH and GPG keys’ de la configuración del perfil en GitHub. Pulsa el botón “New SSH key”.

En el campo ‘Title’ escribe algo como ‘mis llaves’, en ‘Key type’ selecciona ‘Authentication Key’. Dentro del campo de texto “Key”, pega el contenido del portapapeles (teclas Ctrl-V en Windows). Para finalizar, pulsa el botón ‘Add SSH Key’.

Tu llave pública ahora ya es conocida por GitHub, cuando realicemos envíos firmados por nuestra llave privada, sabrá que se trata de nosotros y permitirá la recepción de los cambios de código de nuestro proyecto.

Sincronizar nuestro proyecto con GitHub

Regresando a la terminal donde creamos nuestro proyecto, nos ubicamos en la carpeta de origen ‘blog’, y damos la siguiente instrucción:

1

$ git push origin main

Si se te solicita una contraseña, utiliza la que seleccionaste como frase de seguridad para tu llave SSH en pasos anteriores.

Esto sincronizará los contenidos de nuestro repositorio de código local, con el repositorio remoto que creamos en GitHub.

Verifica en GitHub que el repositorio ya contiene todos tus archivos de proyecto.

Netlify

Es momento de configurar Netlify. Crea una cuenta en Netlify si no tienes ya una. Sigue las instrucciones de esa página para confirmar la creación de tu cuenta.

Crear proyecto

Una vez ingresando a la plataforma de Netlify, dirígete a la pestaña “Sites” y da clic en el botón ‘Add new site’, selecciona la opción “Import an existing project”.

Vamos a conectar tu cuenta Netlify con tu cuenta en GitHub. Da clic en el botón ‘GitHub’ y autoriza a Netlify para que tenga acceso a tu cuenta GitHub. Asegúrate de dar permiso para acceder a tu repositorio ‘mi-blog’ o a todos los repositorios si tienes planeado crear más de un blog.

El siguiente paso es llenar un formulario. El propietario debes ser tú. En ‘Branch to deploy’ selecciona ‘main’. El campo ‘base directory’ queda vacío, mientras que el campo ‘Build command’ debes escribir ‘hugo’. El campo ‘Publish directory’ debe decir ‘public’.

Para finalizar, pulsa el botón ‘Deploy site’.

Esto demorará un poco. El primer despliegue nos proporcionará la configuración que necesitamos para nuestro archivo de configuración de proyecto Hugo.

Configurar proyecto

Da clic a la pestaña ‘Site settings’ en la parte superior de la página. Ahora se visualiza la pantalla de ‘Site details’, busca en la primera sección ‘Site information’ un botón que dice ‘Change site name’. Vamos a cambiar la url de acceso a tu nuevo blog, ya que el nombre por default debe decir algo como ‘glowing-douhua-38475.netlify.app’, que no es muy amigable para que te encuentren en internet. Selecciona un nombre que te agrade y da clic en ‘Save’.

Suponiendo que eligieras ‘superblog’, tu url será ‘https://superblog.netlify.app’, y necesitamos ese dato para cambiar un pequeño pero importante detalle en nuestro archivo de configuración de proyecto Hugo.

Agregar nuevo dato a nuestro proyecto local

Abre el archivo en tu computadora ‘blog/config.yml’ y busca la línea #4:

baseURL: https://urldemiblog.com

Ese dato, ‘https://urldemiblog.com’ vamos a reemplazarlo por la url de tu sitio en Netlify, que aquí resultó ser ‘https://superblog.netlify.app’. Usa la url que personalizaste en pasos previos.

Busca otras coincidencias a lo largo del archivo de configuración para colocar tu url personalizada. Guarda el archivo y ciérralo.

Ahora vamos a sincronizar los cambios.

1
2

$ git commit -m "Cambio de url base de mi sitio"
$ git push origin main

Ahora, GitHub recibió los cambios, y Netlify es notificado y los copiará, ejecutará Hugo en sus propios servidores para generar una nueva versión actualizada de tu sitio y la pondrá en línea automáticamente. Esto demorará un minuto.

Abre tu navegador web y navega a la url personalizada de tu sitio. Et voilà! Tu blog está en línea.

Subir tu primer contenido

Configurar Netlify para gestionar usuarios de tu blog

¿Cómo vamos a publicar tu primer contenido? Netlify deberá ser configurado para funcionar como gestor de autenticación de usuarios para tu blog.

Activar Identidad

Dirígete a la pestaña ‘Site settings’ y da clic en la opción ‘Identity’ del menú de la izquierda. Da clic en el botón ‘Enable Identity’ para activar las funciones de identificación de usuarios.

Ahora se abrieron nuevas opciones en esa misma sección de ‘Identity’. En la sección de ‘Registration’ da clic en el botón ‘Edit settings’. Selecciona ‘Invite only’, luego da clic en el botón ‘Save’, no queremos que cualquiera pueda escribir en tu blog.

Activar servicio Git Gateway

Más abajo en esa misma página, ubica la sección ‘Services’, vamos a activar el servicio ‘Git Gateway’, pulsa el botón ‘Enable Git Gateway’. Si te pide seleccionar un repositorio, apunta al de tu blog.

Invitar usuarios

Por el momento, vamos a invitarte a ti mismo. En el menú superior de Netlify, busca la pestaña “Integrations”. Da clic en el filtro de categorías ‘Identity’ que aparece en un recuadro a la izquierda.

Ahora aparece una integración llamada ‘Netlify Identiy’, da clic en el botón “View”. Se abirá un panel. Busca un botón que dice “Invite users” y da clic en él.

En la ventana emergente coloca tu dirección de correo personal, y pulsa el botón “Send”. Revisa tu bandeja de entrada y busca el mensaje de correo con la invitación, da clic en el enlace “Accept the invite” para aceptar la invitación.

Se abrirá tu blog en el navegador, y una ventana emergente para completar tu registro, ingresa una contraseña nueva (anótala para que no la olvides) y pulsa el botón “Sign up”.

Ahora serás redirigido a la interfaz administrativa del manejador de contenidos de tu blog.

Tu primera publicación

Da clic en el botón “New Posts”, llena el formulario con los detalles de la publicación. Puedes colocar un mensaje de bienvenida.

Te recomiendo que experimentes con el formato de texto Markdown. Es la forma más rápida y eficiente de tener control sobre tus publicaciones. Para usar markdown en el editor de posts, asegúrate de apuntar el botón interruptor del campo ‘Body’ hacia ‘Markdown’.

Al finalizar, pulsa el botón “Publish” en la parte superior de la página.

Netlify CMS guardará tu contenido nuevo en archivos que serán agregados a tu repositorio remoto en GitHub, provocando que Netlify sea notificado del cambio, obtenga una copia actualizada de tu código, ejecute Hugo en su plataforma para crear de nuevo los archivos estáticos y los colocará en su almacenaje web para que sean visibles para todos en la red.

Para ingresar a la interfaz administrativa en cualquier momento, deberás usar como credencial tu correo electrónico personal y la contraseña que acabas de generar, abriendo la url del tipo ‘https://superblog.netlify.app/admin’.

Cambia ‘superblog’ por la url personalizada que elegiste para tu blog.

Cambios posteriores al código

Si deseas hacer cambios posteriormente a tu código, deberás primero sincronizar tu repositorio local con el repositorio remoto en GitHub, que para estos momentos ya tiene contenidos más nuevos que tu versión local.

En la terminal de línea de comandos, ve a la carpeta ‘blog’ y da la siguiente orden:

1

$ git pull origin main

Ahora ya puedes editar tu código localmente otra vez y hacer cambios.

Al concluir tus cambios, sincroniza con GitHub:

1

$ git push origin main

Una vez que GitHub reciba esos cambios, disparará una actualización en Netlify, quedando tu blog renovado en un minuto.

Más ayuda

A lo largo de esta publicación se colocaron enlaces a manuales específicos. Explóralos para abundar en conocimiento sobre las tecnologías que apilamos para construir nuestro blog.

Si quieres enviarme algún comentario, búscame en Mastodon ✌️.