Construir un portafolio/blog con Pelican/Python y GitHub Pages & Actions

Pelican es un generador de sitios web estáticos desarrollado en Python, donde la generación de contenido se realiza con archivos de contenido escritos en markdown y basados ​​en un tema predefinido, construido en HTML, CSS y JavaScript. Además de la naturaleza automatizada del propio Pelican, aquí aprenderemos cómo aprovechar sus características y expandir el proyecto con él, automatizando toda su distribución a través de GitHub Actions y finalmente alojándolo gratis con GitHub Pages.

Intentaré abordar el tema de una manera que sea más fácil de entender para los principiantes, y finalmente, con la base creada aquí, puedes utilizar otros generadores de sitios web estáticos, desarrollados en otros lenguajes de programación, pero con el mismo concepto, como Jekyll (Ruby), HUGO (Go) o Astro (JavaScript), basta una lectura rápida de la documentación para adaptar los comandos.

Serán necesarios algunos conocimientos básicos de Python, Git y GitHub, ya que aunque se utilizan, aquí no serán tan profundos.

Por último, también pondré a disposición en las referencias un repositorio de ejemplo con todo lo hecho aquí para que puedas reutilizarlo, si lo deseas.

¿Qué es GitHub Actions y GitHub Pages?

GitHub Actions es una plataforma de integración y entrega continua, o CI/CD (Continuous Integration, Continuous Delivery) en inglés, donde en definitiva podremos programar tareas y entregar sus resultados de forma automatizada, en base a cambios en los archivos de nuestros repositorios ubicados en GitHub. En este caso, crearemos una tarea, de modo que cuando se realice algún cambio en los archivos de nuestro sitio web, el Action (tareaa o conjunto de tareas) creado genere nuestro sitio web estático nuevamente, con el nuevo contenido, y ponerlo a disposición en una sucursal asociada a nuestras Páginas de GitHub, todo de forma independiente y en la nube.

Y finalmente, GitHub Pages es un alojamiento de sitios web estático gratuito disponible en la plataforma GitHub e integrado con repositorios, con soporte para HTML, CSS y JavaScript.

Creando nuestro repositorio en GitHub

Para comenzar, crearemos un repositorio en nuestra cuenta de GitHub, puedes usar la CLI de GitHub si lo prefieres, sin embargo, por simplicidad usaremos el sitio web.

Simplemente inicia sesión en tu GitHub y haz clic en el ícono “+” en la esquina superior derecha, usando la opción New repository.

Una vez hecho esto, completa los datos del nuevo repositorio como prefieras, por ejemplo:

Con el repositorio ya creado lo clonaremos en nuestra máquina. Para hacer esto, simplemente copie la dirección presentada de su repositorio y use el comando git clone seguido de esta dirección en tu terminal.

Iniciando nuestro proyecto de Pelican

Para iniciar nuestro proyecto en la carpeta local de nuestro repositorio, primero necesitaremos crear el entorno virtual Python:

python -m venv venv

‌‌

Y actívalo con el siguiente comando:

.\venv\Scripts\activate

Para instalar el paquete Pelican a través de pip, usa el siguiente comando:

python -m pip install "pelican[markdown]"

Una vez hecho esto, simplemente usa el siguiente comando para que Pelican genere automáticamente los archivos iniciales para nuestro proyecto:

pelican-quickstart

Él te hará algunas preguntas iniciales y, para ayudarte, te daré una breve explicación de cada una:

1. Como ya estamos en la carpeta del proyecto, simplemente podemos presionar Enter, indicando que iremos a la raíz del proyecto.

> Where do you want to create your new web site? [.]

2. Aquí definiremos el título del sitio web, el que se presenta en el título de la ventana o pestaña del navegador al acceder al mismo.

> What will be the title of this web site? Exemplo de Site com Pelican

3. Su nombre, o el nombre de la empresa propietaria del sitio web.

> Who will be the author of this web site? Amanda Martins Xavier

4. ¿Cuál es el idioma del sitio web? Si escribes en inglés, simplemente presiona Enter, o si escribes en portugués como yo, simplemente escribe pt.

> What will be the default language of this web site? [English] pt

5. Si va a publicar más adelante en tu propio dominio personalizado, colócalo aquí, pero si va a utilizar el subdominio estándar y gratuito de GitHub Pages, puedes simplemente marcar una n.

> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) n

6. Para optimizar la página del blog, limitaremos la cantidad de publicaciones mostradas, habilitando la paginación aquí.

> Do you want to enable article pagination? (Y/n) Y

7. De forma predeterminada, el límite es de 10 publicaciones por página, pero puedes establecer un límite personalizado de publicaciones que se muestran en la página del blog aquí.

> How many articles per page do you want? [10]

8. Aquí definiremos la zona horaria para las publicaciones del sitio. En mi caso, usé el identificador America/Sao_Paulo, pero si el tuyo es diferente, puedes consultar aquí.

> What is your time zone? [Europe/Rome] America/Sao_Paulo

9. Para asegurarse de que las automatizaciones funcionen, marca aquí con Y para confirmar la creación de los archivos indicados.

> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y

10. Como usaremos GitHub Actions y Pages, no haremos uso de los protocolos FTP o SSH, ni de los servicios de Dropbox, S3 y Rackspace Cloud Files. Por lo tanto, si lo deseas, puedes desactivarlos señalando con N, y señalización con y solo para páginas de GitHub.

> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) N
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
> Do you want to upload your website using GitHub Pages? (y/N) y

11. Si no vas a utilizar tu propio dominio personalizado, simplemente indícalo con y.

> Is this your personal page (username.github.io)? (y/N) y

Creando nuestra primera página y publicación

Para crear nuestra primera publicación, simplemente genera un archivo con la extensión .md del formato markdown, dentro de la carpeta generada por Pelican llamada content.

En este archivo colocaremos el título, fecha, categoría y su contenido como en el siguiente ejemplo:

Title: Olá mundo!
Date: 2023-07-02 08:00
Category: Tecnologia

Este é o conteúdo da postagem!

Aquí puedes hacer uso de todas las facilidades que ofrece el lenguaje markdown para crear tus publicaciones, y si el tema elegido tiene características además del título, fecha y categoría, puedes definirlas en el encabezado del archivo junto con los otros tres patrones. de nuestro ejemplo.

Siéntete libre de crear tantas publicaciones y páginas como quieras y organizarlas en subcarpetas dentro de la carpeta content.

Con esto, podrás obtener una vista previa de tu sitio web, con el siguiente comando:

pelican -r -l

Proporcionará una dirección local, pero también podrá acceder a ella a través de http://localhost:8000/, donde podrás consultar los resultados de tu proyecto hasta el momento en tu navegador.

Estructurando nuestro site

El archivo pelicanconf.py es básicamente donde se realizarán todas las configuraciones y personalizaciones. Cada línea de este archivo corresponde a una configuración, ya sea del propio Pelican, que son todas las iniciales que ya están completadas, así como configuraciones de complementos y temas que puedes instalar y usar con el tiempo, por ejemplo, en el tema predeterminado. Puedes definir enlaces de redes sociales y otros en las líneas siguientes:

Para que nuestro repositorio esté más organizado y limpio, crearemos nuestro archivo .gitignore en la raíz de nuestro proyecto, que contendrá la siguiente información:

# Python
__pycache__/

# venv
venv/

# Pelican
output/

Personalizando con temas

Para no extendernos mucho aquí, ni alejarnos del tema principal, por defecto los proyectos se inician con el tema notmyidea, y si quieres usar un tema más limpio como base para crear el tuyo, una buena idea sería sea ​​el tema notmyidea.

Pelican También tiene una CLI para gestionar temas llamada pelican-themes, puedes consultar la documentación haciendo clic aquí. Y si quieres ver los diferentes temas disponibles y creados por la comunidad, está el repositorio oficial del mismo nombre, que puedes consultar haciendo clic aquí.

Cada tema tiene sus peculiaridades y, al igual que los complementos, es posible que requieran algunas líneas y configuraciones más en tu archivo pelicanconf.py, así que echa un vistazo a su documentación para asegurarte de que no te falta nada.

Preparando nuestra GitHub Action

Para crear una Action, simplemente crea un archivo YAML en la raíz del proyecto con un nombre de tu elección, por ejemplo pages.yml, pero dentro de las carpetas .github/workflows, y que contenga la siguiente información:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - uses: nelsonjchen/gh-pages-pelican-action@0.1.5
      env:
        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Además, para que Actions sepa qué dependencias, incluidos temas y plugins, serán necesarios, debes crear el archivo requirements.txt. Para generarlo automáticamente, simplemente usa el siguiente comando:

pip freeze > requirements.txt

Una vez hecho esto, también necesitaremos permitir que nuestra Action lea y escriba nuestro repositorio. Para ello, nos dirigiremos a la pestaña Settings de nuestro repositorio en la web de GitHub, y en el apartado General, dentro de Actions, liberaremos el permiso en Workflow permissions, como se muestra a continuación.

Finalmente, podemos cargar nuestro proyecto en GitHub con los siguientes comandos, y nuestra Action debería iniciarse automáticamente de forma predeterminada:

git add .

git commit -m “🚀 Começando o projeto”

git push

Para verificar el progreso de nuestra automatización, simplemente abre nuestra página de repositorio en GitHub en el navegador y ve a la pestaña Actions.

Configurando nuestro GitHub Pages

En la configuración de nuestro repositorio, en el sitio web de GitHub, simplemente seleccionaremos la rama que nuestra Action creó con los archivos generados, llamada gh-pages, en la opción Branch em Build and deployment, dentro de la sesión Pages, como se muestra abajo:

Si vas a utilizar tu propio dominio personalizado, puedes configurarlo en la misma sesión en Custom Domain, recordando añadir las entradas antes mencionadas en esta documentación y las de DNS de tu proveedor.

Concluyendo y lanzando nuestro proyecto

Para comprobar tu sitio web en vivo, simplemente accede al enlace estándar de GitHub Pages según tu nombre de usuario y repositorio, como en el siguiente ejemplo (https://amandamartinsdev.github.io/pelican-site/) o ingresa a tu dominio personalizado, en caso de haberlo.

Referencias

- Repositorio de ejemplo.

- Site oficial de Pelican.

- Documentación de Pelican.

- Documentación de Action creada por nelsonjchen.