Hugo Framework: Aprende a crear tu primer proyecto; Instalación, configuración y puesta en marcha

Carlos Baeza Negroni

2018/02/01

Categorias: Programación Informática Tecnología
Lenguajes: Go Markdown Html
Contenidos: Videos Código Ejemplos
Tags: Hugo Framework Cms Html Tutorial Guía Markdown Código Ejemplos macOS


Hugo Framework

Hugo Framework

Tabla de Contenidos

1. Introducción

Hugo es un Framework de desarrollo programado en Go, capaz de generar páginas estáticas a partir de plantillas predeterminadas, las cuales funcionan con la sintaxis llamada Markdown de escritura.

La presente publicación tiene como finalidad referirse a la instalación, configuración y puesta en marcha de un proyecto básico realizado sobre el Framework de desarrollo Hugo; En esta oportunidad, nos enfocaremos en el uso de la herramienta más que en el proceso mismo de instalación, asumiendo que, el lector cuenta con cierto conocimiento previo en relación a la instalación de Homebrew y Go en una plataforma macOS.

Decidí llevar a cabo esta publicación con el entusiasmo de poder ejemplificar y graficar el uso de este Framework, debido que, en el corto tiempo que llevo utilizándolo, me ha parecido muy flexible, estable, eficiente, intuitivo y robusto, haciéndolo perfecto para proyectos de pequeña a mediana envergadura.

Pueden revisar más información relacionada con este Framework en su sitio oficial: https://gohugo.io.

1.1. Motivos de Realización

Hoy en día, se debe buscar una solución cada vez más eficiente a la hora de realizar programas computacionales de alta demanda, es por esta razón que, Frameworks como Hugo, entran al juego con su capacidad de tomar, transformar y generar contenido estático en HTML a partir de contenido dinámico de manera automática, y mediante la consola de comandos del sistema operativo.

Cabe mencionar que, Hugo no utiliza bases de datos (tanto relacionales como no relacionales), lo que influye directamente en el rendimiento del programa que se esté desarrollando; A su vez, lo que nos proporciona, son directorios y archivos estáticos en HTML, los que luego son subidos al servidor final (cualquier servidor que sea capaz de interpretar HTML, tampoco utiliza archivos .htaccess, aunque si los soporta), obteniendo todos los beneficios que pudiese implicar la utilización de documentos estáticos en desmedro de las clásicas consultas a una bases de datos, esto, además, previene posibles vulneraciones al desarrollo al estar escrito sólo en HTML y Javascript, sin código que sea ejecutable por parte del servidor ni consultas inyectables por otros tipos de programas maliciosos.

Dicho lo anterior, me gustaría expresar que, el motivo por el cuál se llevó a cabo esta publicación corresponde a un interés tanto académico como profesional, pudiendo ser utilizada por ambos sectores de igual manera, dependiendo del enfoque que se le quiera dar a lo aprendido, o el alcance que pudiese tener el proyecto.

1.2. Método Empleado

El marco teórico se trabajó con casos reales en los que, además de graficar de manera práctica los distintos procesos, se le dió forma en base a una serie de ejemplos y herramientas (como el editor WYSIWYG para lenguaje Markdown), esto para reforzar lo aprendido a medida que se generaba el avance en los contenidos.

1.3. Limitantes

Tal como se trata en el punto 3 de esta publicación, se da por hecho que el lector cuenta con Hombrebrew y Go instalado en su sistema (en el que realizará el ejercicio), además de tener nociones en uso de línea de comandos, html y saber interactuar con un FTP.

1.4. Herramientas Necesarias

La herramientas necesarias para llevar a cabo la actividad son: Editor de texto (el de su preferencia), acceso a internet.

2. Alcances Técnicos

Para fines de esta guía, el hardware y sistema operativo objetivo serán: MacBook Pro, macOS High Sierra; Por otro lado, y con relación al software utilizado para la programación del proyecto (IDE), se utilizó Sublime Text II sin ningún plugin o aditamento, solo con su función de editor de texto.

Al tratarse de un Framework en Go, podemos compilar el proyecto en cualquier arquitectura que permita la instalación de este lenguaje, de manera tal que, se hace independiente del hardware o sistema operativo objetivo, y, al ser una herramienta que crea contenido en HTML estático, este puede ser subido a cualquier servidor compartido de internet (shared hosting), y ser servido sin mayores inconvenientes.

Para la instalación de Go, como para la de Hugo, se utilizó un manejador de dependencias llamado HomeBrew (sólo disponible en macOS), esto debido a que, para el alcance del proyecto, no era necesario un análisis de los recursos involucrados, permitiéndonos la liberad de instalar potenciales dependencias por defecto que no usaremos; Además, esta guía no está pensada para ser usada en un entorno productivo, por lo tanto tampoco corremos riesgo de sufrir algún tipo de problema crítico de rendimiento en medio del proceso.

3. Asumpciones

Para efectos de esta guía, se asume que el lector ya cuenta con Homebrew y Go instalado, ya que, se busca como principal foco, mostrar el Framework de desarrollo Hugo, y no tanto el proceso de instalación (todas las dudas las podemos revisar caso a caso en los comentarios de la publicación).

4. Instalación Homebrew, Go y Hugo

Como fue anunciado en la descripción del proyecto, para llevar a cabo lo que nos proponemos, utilizaremos el manejador de paquetes llamado Homebrew, el cuál se instala de forma muy simple y rápida mediante un script que se debe ejecutar por consola o terminal. Si bien dejaré el código de muestra aquí como referencia, siempre deben acudir al sitio oficial para evitar errores.

Hugo Framework

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Una vez hayamos pegado y ejecutado el script en la consola, comenzará un proceso automático de instalación, el cuál te notificará por la misma terminal cuando finalice de instalar todos sus componentes. Es importante recalcar el hecho que, este comando no debe ejecutarse como root (con sudo), esto afectaría el correcto funcionamiento de Homebrew.

Ahora bien, una vez instalado, es fundamental que evaluemos el estado de nuestra instalación, y si es necesario actualizarla. Para llevar a cabo esto, simplemente debemos ejecutar el comando “brew doctor” en la consola, lo que nos retornará una lista de paquetes que deben ser atendidos (ya sea por actualizaciones o por algún otro tipo de conflictos).

Homebrew Brew Doctor

En este caso en particular, el resultado fue que todos mis paquetes están actualizados, esto debido a que previamente ya lo había ejecutado, por consiguiente no encontró nada anormal dentro de la instalación para reparar o actualizar.

Para poder llevar a cabo estas actualizaciones de repositorios, simplemente debemos ejecutar el comando “brew update” en la consola, lo que actualizará automáticamente todos los paquetes necesarios de forma automática, y hará las correcciones pertinentes de ser necesarias.

Homebrew Brew Update

4.1. Comandos Consola Homebrew

Homebrew es una herramienta que funciona a través de nuestra consola, y es por esta razón que debemos conocer algunos comandos básicos que nos servirán a la hora de trabajar en nuestro proyecto.

La manera más fácil de tener una referencia rápida de estas opciones es a través de la misma consola, y esto se logra mediante el comando “brew –help”, como se muestra en la imagen a continuación.

brew --help

Homebrew Brew Update

4.1.1. Tabla Comandos Homebrew

Comando Descripción Ejemplo
brew –help Comando para ver las opciones disponibles. brew –help
brew doctor Comando para evaluar nuestra instalación, devolverá paquetes con errores o que deban ser actualizados. brew doctor
brew update Comando para actualizar todas las dependencias o paquetes. brew update
brew install paquete Comando para instalar una dependencia o paquete brew install hugo
brew upgrade paquete Comando para actualizar una dependencia o paquete brew upgrade hugo
brew unistall paquete Comando para desinstalar una dependencia o paquete brew unistall hugo
brew switch versión Cambia la versión actual del paquete que tenemos instalado, por la nueva versión proporcionada. brew switch hugo 0.35
brew list –versions paquete Muestra la versión del paquete que tenemos instalado brew list –versions hugo

4.2. Instalando Go

Para instalar Go, simplemente debemos ejecutar el siguiente código en la consola “brew install go”.

brew install go

Destacar que este comando no debe ser ejecutado con sudo, ya que, de lo contrario, podría funcionar con problemas debido a los permisos que necesitará para convivir con Homebrew (recordemos que en la instalación de Homebrew tampoco usamos el comando sudo), y las demás dependencias o paquetes que tengamos instalados y sean complementarios unos de otros.

Homebrew Instalar Go

Algunas personas podrían necesitar configurar rutas y enlaces simbólicos (tal como lo recomiendo la instalación al finalizar), en mi caso no configuré ninguna ruta, puesto que, mi sistema hizo de manera automática el enlace simbólico para utilizar de manera global el comando Go en la consola.

Para revisar que la instalación haya quedado bien, simplemente escriban “go” en la consola, y les debería retornar algunos comandos de ayuda y uso como los explicados más arriba en esta guía.

Comprobar instalación Go

En estos momentos ya tenemos la base para comenzar nuestro proyecto, y esto es dedibo a que Hugo funciona sobre Go, que es el lenguaje de programación de este Framework.

4.3. Instalando Hugo

La instalación de Hugo es tan simple como la de Go (gracias a Homebrew), esta se lleva a cabo ejecutando el comando “brew install hugo” en la consola. Recordar no ejecutar este comando como root (con sudo).

brew install hugo

Instalar Hugo Consola

Desde este punto ya estamos en condiciones de crear nuestro primer proyecto en Hugo, pero antes debemos verificar que nuestra instalación haya quedado bien (tal como verificamos la de Go), para lo cuál utilizamos el comando “hugo version

hugo version

Comprobar Instalación hugo Consola

Si todo está en orden, veremos un mensaje que nos informa la versión de Hugo junto con la arquitectura en la que fue instalado. Ahora sí, vamos a crear nuestro primer proyecto.

5. Creando Nuevo Proyecto Hugo

Lo primero que debemos tener en cuenta a la hora de crear nuestro nuevo proyecto, es la ruta en la cuál lo queremos generar, puesto que, contamos con la libertad de crearlo donde nos sea más útil.

Hugo al ser una dependencia instalada en nuestro sistema, está disponible en cualquier ruta, así que para crear nuestro primer proyecto, primero debemos decidir dónde lo queremos ubicar; En mi caso, fue en el escritorio o desktop, ya que, en lo personal, me resulta más cómodo para acceder y trabajar en él (y como es un proyecto aislado, no requiere una arquitectura puntual o mas elaborada).

Así que, teniendo esto en consideración, nos movemos al directorio en el cuál queremos trabajar (en mi caso el escritorio), utilizando el comando “cd /ruta/al/escritorio”.

cd /Users/cjbaeza/Desktop/

Cambiar Ruta Escritorio

Ahora que estamos en la ruta que nos interesa para trabajar (escritorio), creamos nuestro primer proyecto en Hugo, esto lo logramos ejecutando el comando “hugo new site nombre_directorio_proyecto”, en mi caso, y para efectos de esta guía, nombré mi proyecto como “quickstart”.

hugo new site quickstart

Cambiar Ruta Escritorio

Al hacer esto, lo que conseguimos es crear una nueva instancia de Hugo en el directorio “quickstar”, por ende, todo lo referente al mismo estará contenido dentro de esta carpeta, así que, el siguiente paso, será entrar a nuestro proyecto para comenzar a darle forma y trabajar en él.

Para hacer esto, debemos movernos dentro del directorio con el comando “cd quickstart

cd quickstart

Una vez aquí ya disponemos de todos los comandos que Hugo nos proporciona, ya sea para iniciar el servidor de desarrollo, como para generar los archivos estáticos que finalmente subiremos al servidor de producción (una tabla de estos códigos se entregará en el punto 5.7 de esta guía).

5.1. Estructura Directorios Hugo

Como todo Framework, Hugo tiene su propia estructura de directorios, la cuál es bastante intuitiva y de fácil entendimiento, a continuación dejo una imagen de orientación, y después ahondaremos en los directorios que nos interesan para esta guía.

Iniciar Servidor Hugo

5.2. Iniciando Servidor

Para iniciar el servidor de Hugo, debemos entrar al directorio en el cuál creamos el proyecto (en este caso, el directorio quickstart), y ejecutar el comando “hugo server”, este código levantará automáticamente un servidor interno que escucha el puerto 1313, permitiéndonos, de este modo, poder ver nuestro proyecto ingresando en un navegador.

Además de generar el servidor de prueba, este comando nos mostrará por pantalla información relacionada con nuestro proyecto, como por ejemplo el número de páginas y los archivos estáticos, entre otros; Información que nos ayudará a mantener un control y mejor gestión de los recursos involucrados.

hugo server

Iniciar Servidor Hugo

Como el proyecto está recién creado y “en blanco”, el resultado será una página en blanco, pero no se dejen engañar por esto, ya que, no se considera un error o problema, simplemente debemos agregar una plantilla a nuestro proyecto para que comience a tomar forma, pero siempre es motivante levantar el proyecto aunque sea en blanco.

Para poder ver gráficamente su proyecto, deben ingresar en un navegador a la siguiente dirección: “http://localhost:1313”.

http://localhost:1313

Iniciar Servidor Hugo

5.3. Instalando Plantilla

Por defecto Hugo no trae una plantilla predeterminada, así que, tendremos que buscar alguna que se adecúe a nuestras necesidades, o bien crear una propia desde 0 (el Framework nos permite ambas opciones). Para el caso práctico de esta guía, se utilizará una ya creada llamada “Hugo Classic theme”.

Para buscar la plantilla que más les acomode, pueden revisar la fuente oficial en “https://themes.gohugo.io”.

https://themes.gohugo.io

La plantilla utilizada en esta guía la pueden encontrar aquí: “https://github.com/goodroot/hugo-classic”.

https://github.com/goodroot/hugo-classic

Para instalarlas tenemos dos caminos, en lo personal preferí el “fácil” para hacer la guía mas comprensible para todos.

Esto lo conseguímos descargando y descomprimiendo la plantilla que hayamos elegido, obteniendo la siguiente estructura de directorios.

Ejemplo Directorios Hugo Template

El siguiente paso es llevar este directorio que contiene la plantilla, al directorio “themes” dentro de nuestro proyecto en Hugo.

Directorios Plantilla Hugo

Ahora que ya tenemos los archivos de nuestra plantilla en su lugar, debemos decirle a Hugo que la utilice para mostrar su contenido a nuestros visitantes, para esto hay que modificar el archivo de configuración de nuestro proyecto, ubicado en el directorio raíz del mismo, llamado “config.toml”.

Lo que debemos hacer es indicarle a Hugo cuál es la plantilla que queremos que utilice, esto lo conseguimos con la variable “theme” asociándole el nombre de nuestra plantilla, en este caso, “hugo-classic”.

Directorios Plantilla Hugo

Una vez realizado este pequeño proceso de configuración, y si volvemos a revisar nuestro proyecto en el navegador, podremos observar que ya está desplegando información, y, aunque solo se trate de un encabezado, esto quiere decir que la configuración resultó un éxito y estamos listos para seguir avanzando.

Directorios Plantilla Hugo

5.4. Crear Página Ejemplo

Ya tenemos todo listo para comenzar a agregar contenido en nuestras páginas, así que haremos nuestro “hola mundo” respectivo, y asignaremos un index al proyecto, al cuál llegarán los lectores de nuestro blog por defecto.

Para hacer esto, comenzaremos con el clásico index, para lo cuál se debe crear un nuevo documento en el directorio “content” de nuestro proyecto, con el nombre reservado “_index.md”, el cual se escribe en formato Markdown, como su extensión lo sugiere.

Directorios Plantilla Hugo

Una ve tengamos creado el archivo, solo hará falta comenzar a poblarlo de información (formato Markdown), es recomendable seguir la documentación de Hugo para saber los parámetros de configuración predefinidos de las páginas (como título, descripción, entre otros).

Directorios Plantilla Hugo

En este punto ya podemos entrar a revisar de manera gráfica los resultados de nuestro primero hola mundo en Hugo, accediendo a la url que ya hemos estado utilizando hasta ahora (puede ser necesario un reinicio del servidor Hugo desde la consola).

Directorios Plantilla Hugo

5.4.1. Crear Post Ejemplo

La flexibilidad de Hugo nos permite poder darle el nombre que queramos a nuestro contenido (como posts), por ejemplo, para efectos de esta guía, el nombre que decidí para las notas o posts será “nota”, y esto lo podemos hacer tanto de forma manual como por consola, aunque recomiendo la consola por su simpleza.

Para agregar este nuevo contenido, abrimos nuestra consola o terminal, y ejecutamos el comando “hugo new nota/primer-nota-de-prueba.md”, esto generará automáticamente un directorio nuevo dentro del directorio “content” (de nombre “nota”), ubicado en la raíz del proyecto (el mismo directorio donde dejamos nuestro _index.md), como lo grafica la imagen a continuación.

hugo new nota/primer-nota-de-prueba.md

Directorios Plantilla Hugo

Para graficar y explicar de mejor manera la jerarquía de archivos creados al ejecutar los comandos recién explicados, se agrega una captura a continuación, la que ya nos permite entender a estas alturas el funcionamiento o “lógica” del Framework.

Directorios Plantilla Hugo

5.4.2. Publicar Post Ejemplo Creado

Por defecto, siempre que creemos un nuevo post, Hugo lo dejará en modo “borrador” o “draft”, hasta que nosotros manualmente lo modifiquemos desde su código fuente (modificar el archivo que acabamos de crear por consola), para hacer esto, simplemente se debe eliminar la porción de texto que dice “draft: true”.

Nota de Prueba Borrador

Una vez hayamos eliminado este parámetro desde el archivo, al volver a visitar la página de inicio que creamos (desde el navegador), descubriremos que se agregó de manera automática la entrada o nota en la parte inferior del sitio, por acción del template.

Nota de Prueba Borrador

Ahora, si pinchamos sobre el enlace de la nota, nos llevará al contenido de la misma, y, por si fuera poco, lo hace con una url amigable por defecto, y sin ningún otro tipo de configuración (este slug o url amigable se puede configurar desde el archivo de configuración del proyecto, hubicado en la raíz del mismo).

Nota de Prueba Borrador

5.5. Lenguaje Markdown Plantillas

En la siguiente imagen, se busca conocer un poco más sobre la sintaxis Markdown presente en las plantillas de Hugo.

Como se puede apreciar en la imagen a continuación, en el costado izquierdo, se encuentra expresado el código en lenguaje Markdown, mientras que, al costado derecho, la interpretación en HTML del mismo.

Ejemplo Lenguaje Markdown

5.6. Generación Archivos Estáticos

Hugo es un Framework que permite generar y distribuir de manera estática en HTML el proyecto sobre el cuál se esté trabajando (esta es una de las razones por la cuál se usó en primer lugar), y como ya aprendimos la manera de trabajar con él, ahora nos toca aprender como generar el contenido que finalmente subiremos a nuestro servidor de producción.

Lo primero que debemos hacer para conseguir esto, es abrir la consola del sistema (con la que hemos estado trabajando a lo largo de la guía), y movernos al directorio del proyecto, una vez ahí, debemos ejecutar el comando “hugo” para generar el contenido estático de nuestro proyecto.

Es importante que, cada vez que ejecutemos este comando, eliminemos de nuestro proyecto el directorio “public”, para evitar conflictos de versiones en los archivos estáticos (esta también es una recomendación del equipo del Framework).

hugo

Ejemplo Lenguaje Markdown

Al ejecutar el comando, nos mostrará por pantalla información similar a la que nos muestra al levantar el servidor, esta se compone básicamente de los archivos generados por la instrucción que acabamos de ejecutar; Su finalidad es la de poder saber el volumen del proyecto y revisar si algo no nos hace sentido con relación a la cantidad de archivos generados.

Una vez se haya ejecutado esta instrucción y la pantalla nos muestre el contenido generado por consola, se creará un nuevo directorio dentro de nuestro proyecto llamado “public”, este es el resultado de nuestro proyecto y es lo que queremos subir a nuestro servidor de producción.

Como podrán darse cuenta, Hugo se encargó de generar todas las secciones de nuestro proyecto de manera estática en HTML, de modo tal que, nosotros simplemente debemos preocuparnos de subir ese directorio a un servidor web y nada más, brindándonos un código simple, limpio, y fácil de portar y migrar a cualquier servidor web que sea capaz de soportar HTML.

Ejemplo Lenguaje Markdown

5.7. Tabla Comandos Hugo

Para ejecutar estos comandos se debe estar dentro del directorio del proyecto.

Comando Descripción Ejemplo
hugo new site nombre_proyecto Comando para crear un nuevo proyecto en Hugo. hugo new site demohugo
hugo new sección/slug-nombre-de-la-publicacion.md Comando para crear una página nueva en blanco, la sección puede tener cualquier nombre y esta será ocupada para crear un nuevo directorio con las páginas nuevas que creemos dentro de esa sección (EJ: nota, post, entrada, blog, etc); El slug debe estar siempre con minúscula y sin caracteres extraños como tildes o eñes. hugo new nota/pagina-de-ejemplo.md
hugo Comando para crear el contenido estático de nuestro proyecto, siempre que lo ejecutemos, debemos asegurarnos de eliminar el directorio public previamente creado, para evitar problemas con los archivos. hugo
hugo version Comando para saber la versión de Hugo que estamos ejecutando en el proyecto. hugo version
hugo server Comando para levantar el servidor de desarrollo, al cuál se puede acceder mediante el puerto 1313. hugo server

6. Subiendo Archivos Servidor Producción

Este sin duda es el paso mas simple de esta guía, y consiste en subir el resultado estático de nuestro proyecto a su servidor final en producción.

Para hacer esto simplemente debemos mover todo el contenido de nuestro directorio public, alojado en la raíz del proyecto, al directorio en que se ejecutará en el servidor (EJ: public_html, www, etc), una vez hecho esto, podrán entrar a visitarlo de manera normal siguiendo la url en el navegador (sin necesidad de utilizar puertos).

Ejemplo Lenguaje Markdown

7. Enlaces de Referencia