Hola Blog

Desarrollo de una web estática usando HUGO con la plantilla LoveIt. Adquisición de dominio propio en Namecheap y hosting en Github Pages.

Introducción.

Como primer artículo me pareció buena idea, hacer una guía a través de mi experencia utilizando el gestor de contenidos estáticos HUGO para crear este blog. Esta escrito para toda aquella persona que se anime a crear una web personal utilizando este framework, independientemente de la experiencia que se tenga en el desarrollo web.

Así que no importa si no tienes ningún tipo de conocimientos y nunca has introducido comandos por la terminal.

Antes de empezar debemos tener los siguiente:

Requisitos:

1. Tener instalado el lenguaje de programación Go
2. Instalar HUGO
3. Tener Cuenta en GitHub

Bueno lo de tener cuenta en Github es opcional, pero es el hosting que he elegido y en él se centra la última parte del post.

Si no tienes ni idea de alguno de los programas nombrados te animo de hacer una rápida busqueda en el humilde buscador Google.

Gestor de Contenido Estático

Bueno aquí no te voy a explicar las diferencias entre una web estática y dinámica o porque es mejor HUGO que otros generadores estáticos. Si tienes interes pues lo dicho antes.

Mi motivación principal fue que las web dinámicas necesitan de una base de datos para funcionar, además los frameworks más famosos, Wordpress o Blogger están construidos en PHP.

Y siendo sincero ni me apetece aprender PHP, ni necesito una base de datos para hacer un blog. Además tengo el proyecto de montar mi propio servidor privado y este tipo de de web necesitan muchos más recursos que una web estática.

De los diferentes gestores de contenido estático me decante por HUGO por el hecho de que Go un lenguaje que me gusto desde el primer momento por su similitud al c y decidí darle una oportunidad.

Así que al tema.

Conociendo a HUGO.

Una vez instalado HUGO nos dirigimos a nuestro terminal, para comprobar la correcta instalación. Introduciendo el comando hugo versionnos dirá si existe una versión, y cuál es la que estamos utilizando.

Para empezar un nuevo proyecto se hace uso del comando hugo new siteseguido del nombre de nuestro proyecto. Hecho esto, HUGO nos crea una carpeta con el nombre que le hemos asignado. Ahora nos dirijimos hacia ella y vemos que se han creado diferentes archivos dentro.

Si no estas familiarizado con la terminal de tu pc abajo tienes un ejemplo.

#Esto es un comentario
#No se debe escribir ~$ 
~$ hugo version
#Algo asi debera salir el +extended es por la versión extendida
hugo v0.92.1+extended linux/amd64
#Creamos un proyecto.
#miweb es el nombre que le hemos puesto a nuestro proyecto.
~$ hugo new site miweb
#Resultado
Congratulations! Your new Hugo site is created in .....   
#Vamos al nuevo directorio creado "cd"
~$ cd miweb
#Comando para ver contenido del directorio; en Linux "ls", en Windows "dir"
~/miweb$ ls
#HUGO ya nos ha creado un serie de directorios
archetypes  config.toml  content  data  layouts  static  themes

Las siguientes tablas muestran una breve descripción de los archivos de nuestro proyecto.

Más adelante el propio programa creará dos carpetas más

Descargar Pantillas.

Ahora toca elegir el tema que definira el aspecto de nuestra web, puedes elegir la plantilla que más te guste en https://themes.gohugo.io/.

Se pueden descargar de dos formas:

1. Dirigiendote al repositorio del tema, copias su contenido en download ZIP y descomprimes los archivos en la carpeta themes .(Recomendación)

2. En la pantalla de comandos, en el directorio de nuestro proyecto introduces git init y acto seguido git submodule add más URL_Repo_Tema espacio Carpeta_themes.

~/miweb$ git init    
 
~/miweb$ git submodule add https://github.com/dillonzq/LoveIt.git themes/loveit     

Si has elegido una plantilla diferente puedes continuar la guía en Creando contenido.

Configuración LoveIt. (Ublogger)

En mi caso elegí el tema LoveIt, sin embargo si vas ha seguir esta opción tengo una mala noticia. Por lo visto este tema se encuentra abandonado y aunque siga existiendo el repositorio no se encuentra mantenido.

Aunque no todo son malas noticias, un usuario de Github a ramificado el proyecto para mantenrlo el mismo, añadiendo alguna que otra mejora. Puedes encontrar esta plantilla bajo el nombre Ublogger.

De todas formas estos dos temas, LoveIt y Ublogger se configuran de la misma forma. Posiblemente en un futuro no muy lejano me cambie a esta nueva versión pero de eso hablaré en otro post.

Bueno…., seguimos.

Antes de comenzar a llenar de contenido nuestra página, vamos hacer todas las configuraciones necesarias para no tener ningún mensaje de error en el terminal.

Primero abrimos el archivo default.md de la carpeta archetypes y cambiamos el contenido entre los guiones por el siguiente código. Esta será la configuración por defecto de los artículos que publiquemos.

title: "{{ replace .TranslationBaseName "-" " " | title }}"
subtitle: ""
date: {{ .Date }} 
lastmod: {{ .Date }} #Ultima actualización
#draff "true" para activar (modo borrador), no se ven los cambios 
draft: false 
author: ""
authorLink: ""
description: ""

tags: []
categories: []

hiddenFromHomePage: false
hiddenFromSearch: false
#imagen cabecera artículo
featuredImage: "" 
#imagen artículo en home
featuredImagePreview: ""

#toc "true" activa el indice
toc:
  enable: true
#math "true"formulas matemáticas
math:
  enable: false
#imagenes se muestran en la galería
lightgallery: false
license: ""

Ahora vamos a configurar el aspecto básico de nuestra web. Vamos a modificar el el archivo conf.toml por el siguiente archivo

#se debe cambiar en el momento de subir nuestra pagina
baseURL = "http://example.org/" 
# [en, zh-cn, fr, ...] lenguas predeterminadas "es"=español
defaultContentLanguage = "es"
# language code
languageCode = "es"
title = "My New Hugo Site"

# Change the default theme to be use when building the site with Hugo
theme = ""

[params]
  # LoveIt theme version
  version = "0.2.X"
# Parametros del perfil de home
 [params.home.profile]
     enable = true
     # Gravatar Email for preferred avatar in home page
     gravatarEmail = ""
     # URL of avatar shown in home page. Usa favicon
     avatarURL = ""
     # title shown in home page (HTML format is supported)
     title = "Titulo web"
     # subtitle shown in home page
     subtitle = "Texto generado con typeit"
     # whether to use typeit animation for subtitle
     typeit = true
     # whether to show social links
     social = true
     # disclaimer (HTML format is supported)
     disclaimer = ""
# Si queremos añadir nuetras redes sociales. Mira la documentación para más información
  [params.social.Github]
    # weight when arranging icons (the greater the weight, the later the icon is positioned)
    weight = 1
    #your social ID
    id = ""
    #prefix of your social link
    prefix = "https://github.com/"
    #content hovering on the icon
    title = "Github"
   [params.home.posts]
      enable = true
      paginate = 3
[menu]
  [[menu.main]]
    identifier = "posts"
    # you can add extra information before the name (HTML format is supported), such as icons
    pre = ""
    # you can add extra information after the name (HTML format is supported), such as icons
    post = ""
    name = "Posts"
    url = "/posts/"
    # title will be shown when you hover on this menu link
    title = ""
    weight = 1
  [[menu.main]]
    identifier = "tags"
    pre = ""
    post = ""
    name = "Tags"
    url = "/tags/"
    title = ""
    weight = 2
  [[menu.main]]
    identifier = "categories"
    pre = ""
    post = ""
    name = "Categories"
    url = "/categories/"
    title = ""
    weight = 3
  [[menu.main]]
    identifier = "about"
    pre = ""
    post = ""
    name = "About"
    url = "/about/"
    title = ""
    weight = 4

# Markup related configuration in Hugo
[markup]
  # Syntax Highlighting (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false is a necessary configuration (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

Creando contenido.

Configurado default.md y conf.toml con las opciones disponible ennustra plantilla,vamos a ir a la carpeta themes y copiamos el contenido de layout en nuestra carpeta principal del mismo nombre.

Ahora para empezar a crear contenido es tan fácil como introducir hugo new más la Dirección/Nombre_Artículot.md. El contenido en HUGO se escribe en Markdown por eso la extensión debe ser .md .

#Para crear nuestro primer artículo
~/miweb$ hugo new posts/prueba.md    

Con esto hemos creado dentro de la carpeta content una archivo llamado prueba dentro de una subcarperta llamada post. Abrimos prueba.md con cualquier editor de texto ,empezamos a escribir y guardamos.

Por último introducimos el comando hugo server . Para ver los resultados, en nuestro navegador introducimos la dirección http://localhost:1313/ y listo.

~/miweb$ hugo server     

Después de esto se crearán dos carpetas más en nuestro proyecto resourse y public.

#Crear una página de contacto   
~/miweb$ hugo new about.md     

Existe información más detallada acerca de la configuarción de la plantilla en la web demo de los desarrolladores.

• LoveIt
• Ublogger

Hosting.

En la documentación de HUGO te recominda diferentes hosting gratuitos compatibles. De todas las opciones me decanté por Github Pages.

Primero creamos un repositorio en Github, este debe tener el nombre especial de Tu_Usuario.github.io .Seleccionamos que sea publico y dejamos sin seleccionar las opciones de abajo.

Volvemos a nuestra consola e introducimos hugo -d public/docs , esto va a crear una subcarpeta llamada docs en public con los archivos estáticos de nuestra web (HTML, CSS, JavaScript).

Esta carpeta (docs), la importemos al repositorio de github. Esto se puede hacer de dos formas:

1. Seleccionas subir archivos y arrastra la carpeta docs. Puedes tener problema al subir ya que de esta forma solo se pueden subir 100 files simultaneos. tip(carpeta lib)
2. Subirlo mediante el gestor de versiones git , es un poco más complicado pero más útil a la larga.(Recomendación)

En la terminal nos dirigimos al directroio public de nuestro proyecto y hacemos un git init seguido de un git add . para concluir git commit -m " Version 0.0".

~/miweb/public$ hugo init     
~/miweb/public$ hugo add .     
~/miweb/public$ hugo commit -m "Mensaje cualquiera"     

La forma de apuntar al repositorio de github se puede observar nada más crearse el repositorio en github. A continuación puedes ver los comandos que se deben ejecutar.

   git remote add origin https//github.........    
   git branch -M master   
   git push -u origin master

Acto seguido te pedira tu usuario de github y la password asociada a tu token.

Ahora debemos añadir un nuevo archivo al repositorio con la siguiente ruta .github/workflows/gh-pages.yml. Puedes compiar la dirección anterior como nombre y github creará automáticamente un archivo gh-pages.yml en la carpeta .github/workflows/.

En este archivo es un flujo de trabajo para decir que vamos a trabajor con Go .EL contenido debe ser el siguiente código:

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Por último debemos subir el archivo conf.toml de tu web y cambiar dentro de él la opción baseURL por el nombre de tu repositorio.

En total nuestro proyecto en Github debe contener tres archivos:

• El archivo conf.tolm apuntando correctamente.
• Carpeta docs donde se encuentran los contenidos estáticos.
• Ejecutable github/workflows/gh-pages.yml.

Solo queda el último paso, en nuestro repositorio de github nos dirigimos a la pestaña *settings una vez ahí vamos a Pages, en source cambiamos la rama de /root a docs/. Con estos cambios ya puedes ver tu web introduciendo tu Url de github.

• actualizaciones :
  • hacer un pull si fuera necesario agrgar un allow
  • push

¿Cuál es mi nombre?

Este apartado es opcional.

En mi caso quería un aspecto más profesional y no quería tener asociado un .github.io a mi portal. Por eso la desición de comprar un dominio.

Existen diferentes empresas que ofrecen eso servicios:

• Namecheap
• Google Search
• etc…

Yo me decidí por Namecheap, tu puedes elegir cualquiera.

Ahora toca elegir el nombre de mi web.

• Diferentes lugares y tutoriales de dominios
• Experiencia Namecheap

Apuntando a Mi Host.

Ya con la dirección dada de alta algo que tarda menos de 48h, nesesitamos redirigir el lugar donde se encuentra hospedada nuestra página a nuestro nuevo dominio. Esto se consigue apuntando las direciones DNS de nuestro hosting*( Github Pages )* al del proveedor de nuestro dominio.

La manera mas fácil de comprobarlo es por consola por medio del comando dig y la dirección .github.io.

~$ dig UserGitHub.github.io    
#Entre más información se deberá ver 
;; ANSWER SECTION:
UserGitHub.github.io.		1531	IN	A	185.199.111.153
UserGitHub.github.io.		1531	IN	A	185.199.109.153
UserGitHub.github.io.		1531	IN	A	185.199.110.153
UserGitHub.github.io.		1531	IN	A	185.199.108.153

Una vez hecho, entras en tu cuenta de namechep y te dirige a las opciones avanzadas de tu domino y añades las 4 DNS de Github, cambias en el nombre para apuntar a tu URL TuCuenta.github.io.

Ya solo queda un último paso, volver a las opciones de nuestro repositorio en Github y añadir el nombre de nuestro dominio.

Al hacer esto se crea un archivo llamado CNAME dentro de docs que redirigirá el tráfico de Github pages a la dirección elegida.

Ampliaciones pendientes.

Aunque el objetivo de este proyecto era poner en marcha el blog de manera funcional, lo más rápido posible. Todavía hay cosas que tengo pendiente para dejarlo a mi gusto. A continución presento un lista que se irá actualizando de futuras impletaciones.

• Añadir google analitycs
• Añadir idiomas
• Cambio de tema a Ublogger
• Sistema de comentarios
• Cambio a un servidor privado