Después de años de construir software y escribir documentación técnica, decidí crear un blog para compartir mi experiencia y ayudar a otros en viajes similares.
Elegir la plataforma
Mientras que la construcción de mi propio script de publicación Markdown-to-HTML es una idea para el futuro, mi prioridad inmediata fue conseguir que el blog se conectara rápidamente.
Hoy en día, no creo que haya una dificultad en la creación de un sitio web personal. Hay una amplia variedad de opciones que ayudan en este esfuerzo.
- CMS (por ejemplo, WordPress, Content Hub, Joomla, etc.): Mientras que las plataformas como WordPress son poderosas, se sentían excesivas para un blog de contenido estático.
- Jekyll: Este software parece ser perfecto y ampliamente utilizado por otros desarrolladores para alojar blogs, pero debido a mi falta de experiencia con Ruby, he elegido no usar esto.
- Hugo. Hugo está escrito en Go y utiliza la conocida sintaxis de las plantillas de Go (si sucede que codifica mucho en Go), mientras renderiza páginas en Markdown (similar a Jekyll).
- 11ty, Astro, Hexo y otras alternativas basadas en Node.js. Es una cuestión de preferencia, pero personalmente, decidí minimizar el uso de las herramientas de Node.js. Aunque hay muchas herramientas poderosas, el ecosistema de Node.js es notorio por cambiar rápidamente, lo que a menudo me llevó a no poder ejecutar los antiguos proyectos que naturalmente tenían muchas dependencias antiguas.
Encuentro con Hugo
Después de haber producido una cantidad sustancial de documentación sobre mis proyectos relacionados con el software en el pasado, me siento muy seguro de usar Markdown y un editor de texto basado en terminales para mi escritura.
Utilización de un repositorio GitHub
Anteriormente, ya había creado un sitio web de GitHub Pages con archivos de sitio y conectado un dominio a él, por lo que para llenar archivos en un repo existente, debe introducir el siguiente comando:
hugo new site . --force
Esto llenará el directorio del repositorio actual con los archivos que son necesarios para ejecutar el sitio web de Hugo. Después de eso, era necesario configurar el tema y otros parámetros en elhugo.tomlDespués de que todo esté configurado, es posible ejecutar el servidor escribiendo el comando:hugo server
Executar el servidor en modo de desarrollo
En este momento, el sitio web está disponible desdelocalhostDesde que desarrollo en una VM de nube remota, accediendo al servidor local Hugo a través delocalhostEra necesario exponer de forma segura la instancia localhost al mundo exterior - para tales necesidades, se utiliza un proxy reverso.
Mientras que los balanceadores de carga y los proxies inversos como Nginx son bastante comunes y populares, eligióCaddypara servir mi sitio web de desarrollo porque establece certificados SSL (a través de Let's Encrypt) sin esfuerzo.CaddyEstá hecho conCaddyfile, donde para el dominio de interés escribe unreverse_proxyDeclaración con el puerto necesario:
test-blog-domain.com {
reverse_proxy localhost:1313
}
Después de iniciar Caddy con la configuración anterior, el sitio web de desarrollo estará disponible desdehttps://test-blog-domain.com(Dado que unALos registros DNS paratest-blog-domain.comse rellena con una dirección IP pública de la VM).
Añadir un tema
Hugo tiene una serie de temas gratuitos que están disponibles públicamente en GitHub.Lo que es necesario hacer para instalar uno es clonar un repositorio con un tema y luego actualizar elthemeParámetros enhugo.tomlElegí un tema llamadocactusDespués de la instalación, tengo un error de construcción que se queja de que el modelo async de Google Analytics no se encuentra:
Error: error building site: render: failed to render pages: render of "/" failed: "/home/user/projects/nexo-tech.github.io/themes/cactus/layouts/_default/baseof.html:3:3": execute of template failed: template: index.html:3:3: executing "index.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:47:16: no such template "_internal/google_analytics_async.html"
make: *** [Makefile:2: up] Error
Una solución para tal problema se puede encontrar engithubLa comunidad Hugo está activa, y muchos problemas -incluido este error de Google Analytics- tienen parches o discusiones existentes en GitHub.
Después de corregir otras advertencias de depreciación, el sitio comenzó a funcionar:
Implementar un sitio web en CDN: Páginas de GitHub
Hay numerosas maneras de implementar un sitio web estático, y en la mayoría de los casos, se requiere tener un alojamiento o servidor. Usualmente, estos no son gratuitos o tienen un plan restringido; sin embargo, hay excepciones a esto, como las páginas de GitHub. Es posible servir contenido estático de una rama particular de un repositorio de GitHub o usar acciones de GitHub pre-construidas que se basan en crear artefactos de construcción y implementarlos de una manera personalizada.
Saber que, las cuentas personales de GitHub son muy limitadas en el espacio de almacenamiento de artefactos, y es tedioso gestionar ese espacio de almacenamiento, opté por la solución más simple donde los activos del sitio web estáticos se actualizan en una rama de git predefinida (gh-pagesAfortunadamente, hayactionsespecíficamente para Hugo, precisamente para este propósito:
- acciones-hugo por Shohei Ueda. Una manera sencilla de configurar Hugo en un entorno de acciones de GitHub
- acciones-gh-pages También, por Shohei Ueda, esta acción impulsa activos estáticos a la rama especificada.
Aquí está el código de un flujo de trabajo de acciones de GitHub que desplegará Hugo en gh-pages. Tenga en cuenta que si hay necesidad de un dominio personalizado, un archivo CNAME debe ser copiado a lapublicEl director antes de dirigirgh-pagesAdemás, los permisos de flujo de trabajo de su repositorio deben estar configurados en "Leer y escribir" (se puede encontrar enSettings > Actions > General) de
name: Build and Deploy Hugo
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v3
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: 'latest'
extended: true
- name: Build site
run: hugo --minify
- name: Add CNAME file
run: cp CNAME public/CNAME
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
publish_branch: gh-pages
Una vez que la implementación pase, el sitio debe ser cargado a GitHub CDN. Asegúrese de configurar las páginas de GitHub para la rama que contiene artefactos construidos en caso de que el sitio web no funcione.
Con Hugo configurado y desplegado, ahora puedo centrarme en lo que importa: compartir insights técnicos de mi experiencia.Espero que esta guía ayude a otros que buscan construir un blog simple y confiable para su trabajo.
Recursos relacionados
- Repositorio para este sitio web
- Hugo comienza rápidamente
- Configurar la configuración de DNS para las páginas de GitHub
- Temas de cactus para Hugo
- Google Analytics en Hugo
- Caddy reverso proxy de inicio rápido
