Construir um portfólio/blog com Pelican/Python e GitHub Pages & Actions
O Pelican é um gerador de sites estáticos desenvolvido em Python, onde a geração do conteúdo é feita com os arquivos dos conteúdos escritos em markdown, e em cima de um tema pré-definido, construído em HTML, CSS e JavaScript. Além da própria natureza automatizada do Pelican, aqui iremos aprender como tirar proveito de suas facilidades, e expandir o projeto com ele, automatizando toda a sua distribuição através do GitHub Actions, e hospedando por fim e gratuitamente com o GitHub Pages.
Tentarei abordar o tema de forma que facilite o entendimento para pessoas iniciantes, e por fim, com a base criada aqui, você poderá utilizar outros geradores de sites estáticos, desenvolvidos em outras linguagens de programação, porém com o mesmo conceito, como por exemplo: Jekyll (Ruby), HUGO (Go) ou Astro (JavaScript), bastando apenas uma breve lida nas documentações para adaptar os comandos.
Alguns conhecimentos básicos em Python, Git e GitHub serão necessários, pois embora utilizados, não serão tão aprofundados aqui.
Por fim, irei disponibilizar também nas referências, um repositório de exemplo com tudo feito aqui para você reutilizar, caso deseje.
O que é o GitHub Actions e GitHub Pages?
O GitHub Actions é uma plataforma de integração e entrega contínuas, ou CI/CD (continuous integration, continuous delivery) em inglês, onde resumidamente podemos programar tarefas e entregar o resultado delas de forma automatizada, com base nas mudanças nos arquivos dos nossos repositórios localizados no GitHub. Neste caso, iremos criar uma tarefa, para que quando qualquer alteração seja feita nos arquivos do nosso site, a Action (tarefa ou conjunto de tarefas) criada, gere o nosso site estático novamente, com o novo conteúdo, e disponibilize em uma branch associada ao nosso GitHub Pages, tudo de forma independente e na nuvem.
E por fim, o GitHub Pages é uma hospedagem de sites estáticos gratuita disponível na plataforma da GitHub e integrada aos repositórios, com suporte a HTML, CSS e JavaScript.
Criando o nosso repositório no GitHub
Para começarmos, iremos criar um repositório na nossa conta do GitHub, você pode utilizar o GitHub CLI se preferir, porém, para simplificar iremos utilizar o site.
Basta entrar na sua no GitHub, e clicar no ícone de “+” no canto superior direito, utilizando a opção “New repository”.
Feito isso, preencha os dados do novo repositório como preferir, como por exemplo:
Com o repositório já criado, iremos cloná-lo na nossa máquina. Para isso, basta copiar o endereço apresentado do seu repositório, e utilizar o comando “git clone” seguido desse endereço no seu terminal.
Iniciando o nosso projeto do Pelican
Para iniciarmos o nosso projeto na pasta local do nosso repositório, primeiro precisaremos criar o ambiente virtual do Python:
python -m venv venvE ativá-lo com o seguinte comando:
.\venv\Scripts\activatePara instalar o pacote do Pelican através do pip, utilize o comando abaixo:
python -m pip install "pelican[markdown]"
Feito isso, basta utilizar o comando abaixo para que o Pelican gere automaticamente os arquivos iniciais do nosso projeto:
pelican-quickstartEle irá te fazer algumas perguntas iniciais, e para ajudar, irei fazer uma breve explicação de cada uma:
1. Como já estamos na pasta do projeto, podemos simplesmente pressionar Enter, sinalizando que seguiremos na raíz do projeto.
> Where do you want to create your new web site? [.]2. Aqui definiremos o título do site, aquele apresentado no título da janela ou da aba do navegador ao acessá-lo.
> What will be the title of this web site? Exemplo de Site com Pelican
3. O seu nome, ou da empresa da qual é proprietária do site.
> Who will be the author of this web site? Amanda Martins Xavier4. Qual a linguagem do site, sendo que, caso você escreva em inglês, basta pressionar Enter, ou caso escreva em português, basta digitar “pt”.
> What will be the default language of this web site? [English] pt
5. Caso você vá publicar mais tarde em um domínio personalizado e próprio, coloque-o aqui, mas caso vá utilizar o sub-domínio padrão e gratuito do GitHub Pages, você pode apenas marcar um “n”.
> Do you want to specify a URL prefix? e.g., https://example.com (Y/n) n6. Para otimizar a página de blog, limitaremos a quantidade de postagens exibidas, habilitando aqui a paginação.
> Do you want to enable article pagination? (Y/n) Y7. Por padrão, o limite é 10 postagens por página, mas você pode definir um limite personalizado de postagens exibidas na página de blog aqui.
> How many articles per page do you want? [10]8. Aqui definiremos o fuso horário das postagens do site, no meu caso utilizando o identificador “America/Sao_Paulo”, mas caso o seu seja diferente, você poderá consultar aqui.
> What is your time zone? [Europe/Rome] America/Sao_Paulo9. Para garantir o funcionamento das automações, sinalize aqui com “Y” para confirmar a criação dos arquivos indicados.
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) Y10. Como iremos utilizer o GitHub Actions e Pages, não iremos fazer uso dos protocolos FTP ou SSH, tampouco dos serviços Dropbox, S3 e Rackspace Cloud Files, portanto, se desejar, você poderá desativá-los sinalizando com “N”, e sinalizando com “y” apenas para o GitHub Pages.
> 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) y11. Caso você não vá utilizar um domínio personalizado e próprio, basta sinalizar com “y”.
> Is this your personal page (username.github.io)? (y/N) yCriando nossa primeira página e postagem
Para criarmos a nossa primeira postagem, basta criar um arquivo com a extensão “.md” do formato markdown, dentro da pasta gerada pelo Pelican chamada “content”.
Neste arquivo colocaremos, título, data, categoria e o seu conteúdo como no exemplo abaixo:
Title: Olá mundo!
Date: 2023-07-02 08:00
Category: Tecnologia
Este é o conteúdo da postagem!
Aqui você poderá fazer uso de todas as facilidades que a linguagem markdown disponibiliza para criação das suas postagens, e caso o seu tema escolhido possua características além do título, data e categoria, você poderá defini-las no cabeçalho dos arquivos junto com as outras três padrões do nosso exemplo.
Fique livre para criar quantas postagens e páginas você desejar, e organizá-las em subpastas dentro da pasta “content”.
Com isso, você poderá pré-visualizar o seu site, com o comando abaixo:
pelican -r -l
Ele irá disponibilizar um endereço local, mas você pode acessar também através de http://localhost:8000/, onde você poderá conferir no seu navegador o resultado do seu projeto até aqui.
Estruturando o nosso site
O arquivo “pelicanconf.py” é basicamente onde todas as configurações e personalizações serão feitas. Cada linha desse arquivo corresponde a uma configuração, seja do próprio Pelican, que são todas as iniciais que já vem preenchidas nele, como também das configurações de plugins e temas que você pode instalar e utilizar com o tempo, como por exemplo, no tema padrão, é possível definir os links de redes sociais e outros nas linhas abaixo:
Para deixarmos o nosso repositório mais organizado e limpo, iremos criar na raiz do nosso projeto, o nosso arquivo “.gitignore”, contendo as seguintes informações:
# Python
__pycache__/
# venv
venv/
# Pelican
output/
Personalizando com temas
Para não estendermos demais por aqui, ou fugirmos do assunto principal, por padrão, os projetos são iniciados com o tema “notmyidea”, e caso você queira utilizar um tema mais limpo como base para criar o seu, uma boa ideia seria o tema “simple”.
O Pelican também possui uma CLI para gestão de temas chamada “pelican-themes”, que você poderá consultar a documentação clicando aqui. E caso deseje olhar os diversos temas disponíveis e criados pela comunidade, existe o repositório oficial de mesmo nome, que você pode conferir clicando aqui.
Cada tema tem suas peculiaridades, e assim como os plugins, podem requerer algumas linhas e configurações a mais no seu arquivo “pelicanconf.py”, então dê uma olhada na documentação deles para garantir que não estará faltando nada.
Preparando a nossa GitHub Action
Para criarmos uma Action, basta criar na raiz do projeto um arquivo YAML com nome de nossa preferência, por exemplo “pages.yml”, porém, dentro das pastas “.github/workflows”, e contendo as seguintes informações:
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}}
Ainda, para que a Actions saiba quais dependências, incluindo temas e plugins, que precisarão serem instalados, será necessário criar o arquivo “requirements.txt”. Para gerarmos o mesmo, de forma automática, basta utilizar o comando abaixo:
pip freeze > requirements.txt
Feito isso, precisaremos também permitir a leitura e escrita do nosso repositório por parte da nossa Action. Para isso, iremos na aba “Settings” do nosso repositório no site do GitHub, e na sessão “General”, dentro de “Actions”, liberaremos a permissão em “Workflow permissions”, conforme abaixo.
Por fim, podemos subir o nosso projeto para o GitHub com os comandos abaixo, e a nossa Action já deverá ser iniciada automaticamente por padrão:
git add .
git commit -m “🚀 Começando o projeto”
git push
Para conferir o andamento da nossa automação, basta abrir a página do nosso repositório no GitHub no navegador, e ir na aba “Actions”.
Configurando o nosso GitHub Pages
Nas configurações do nosso repositório, no site do GitHub, iremos apenas selecionar a branch que a nossa Action criou com os arquivos gerados, chamada “gh-pages”, na opção “Branch” em “Build and deployment”, dentro da sessão “Pages”, conforme abaixo:
Caso vá utilizar um domínio próprio e personalizado, você poderá configurá-lo nessa mesma sessão em “Custom domain”, lembrando de adicionar as entradas citadas nesta documentação também nas configurações de DNS do seu provedor.
Concluindo e conferindo o nosso projeto no ar!
Para conferir o seu site no ar, basta acessar o link padrão do GitHub Pages conforme o seu nome usuário e repositório, como no exemplo abaixo (https://amandamartinsdev.github.io/pelican-site/), ou acessar o seu domínio personalizado, caso tenha utilizado.
Referências
- Documentação da Action criada por nelsonjchen
A Revelo Content Network acolhe todas as raças, etnias, nacionalidades, credos, gêneros, orientações, pontos de vista e ideologias, desde que promovam diversidade, equidade, inclusão e crescimento na carreira dos profissionais de tecnologia.