Introdução #

Seja bem-vindo ao meu blog. Este é o primeiro de muitos posts que você irá ler aqui. A motivação para este primeiro post é explicar e documentar como foi o processo de criação deste blog.

Parte não técnica #

Motivação #

• Motivo 1: Centralizar os conteúdos que crio de maneira escrita.
• Motivo 2: Uma maneira mais simples de criação de conteúdo comparada aos vídeos do YouTube.
• Motivo 3: Utilizar o blog não somente como forma de criação de conteúdo, mas também como documentação.

Como será organizado o conteúdo do blog? #

A ideia do blog é ter dois tipos principais de postagens:

1. Posts: São conteúdos mais robustos que combinam teoria, exemplos práticos e frequentemente estão prontos para aplicação em ambientes reais e produtivos.

2. Pills: Conteúdos simples e rápidos que expressam e compartilham dicas, aprendizados do dia a dia ou reflexões de maneira mais desestruturada.

Ainda teremos vídeos no YouTube? #

SIM! A ideia é continuar com as duas maneiras de conteúdo, e muitas vezes um pode complementar o outro, como: um vídeo e post sobre o mesmo assunto, onde compartilho os principais links, documentações, códigos e referências utilizados no vídeo.

Parte técnica #

O blog foi projetado para funcionar de maneira relativamente simples. A ideia principal foi buscar uma stack que não demande muita manutenção. Para atender esses requisitos utilizei o framework Hugo junto com um tema da comunidade, assim foi possível focar mais na parte de criação de conteúdo. No entanto, realizei algumas customizações que demandaram certo tempo de desenvolvimento.

Hospedagem #

Para a hospedagem, estou utilizando o GitHub, onde mantenho dois repositórios:

1. Repositório privado: contém toda a estrutura do blog, os posts em Markdown, configurações e pipeline de CI/CD.
2. Repositório público (brunoxd13.github.io): contém apenas o artefato final produzido pelo build do Hugo, servido pelo GitHub Pages.

Escolha do framework #

Os principais fatores que influenciaram a escolha do Hugo foram:

1. Performance: Hugo é extremamente rápido na geração de páginas. O build completo deste blog leva poucos segundos.
2. Simplicidade: O conteúdo é escrito em Markdown puro, sem necessidade de dependências externas, database ou backend.
3. Sem dependências pesadas: Diferente de alguns frameworks, Hugo é apenas um binário.
4. Suporte nativo a i18n: Possui suporte integrado para sites multilíngues.
5. Ecossistema de temas: Existe uma grande comunidade que suporta temas de fácil customização. O tema escolhido foi o Typo, minimalista e focado em conteúdo.

Arquitetura e estrutura do projeto #

A estrutura principal do projeto segue a organização padrão do Hugo com algumas customizações:

my-blog/
├── .github/workflows/     # Pipeline de CI/CD (GitHub Actions)
├── archetypes/            # Templates para novos conteúdos
├── assets/
│   ├── css/custom.css     # Estilos customizados
│   └── js/                # Scripts de customização (theme-toggle, TOC)
├── content/
│   ├── en/                # Conteúdo em inglês
│   │   ├── posts/         # Artigos completos
│   │   ├── pills/         # Conteúdos rápidos
│   │   └── about/         # Página sobre
│   └── pt-br/             # Conteúdo em português
│       ├── posts/
│       └── pills/
├── i18n/                  # Arquivos de tradução
├── layouts/               # Overrides de templates do tema
│   ├── partials/          # Componentes reutilizáveis
│   ├── shortcodes/        # Shortcodes customizados
│   └── _default/          # Overrides de templates padrão
├── static/                # Arquivos estáticos (favicons)
├── themes/                # Temas (git submodules)
│   └── typo/
├── hugo.toml              # Configuração principal do Hugo
└── Makefile               # Comandos mais utilizados no dia a dia

Como criar o seu blog #

Para criar um blog utilizando o Hugo, o processo é bem simples e rápido. Basta seguir os passos abaixo:

 1# Criando a estrutura do blog
 2hugo new site <your-blog-name> --config toml
 3cd <your-blog-name>
 4
 5# Adicionando o tema typo como submodule
 6git submodule add --depth=1 https://github.com/tomfran/typo.git themes/typo
 7git submodule update --init --recursive
 8
 9# Configurando o tema no arquivo de configuração
10echo 'theme = "typo"' >> hugo.toml
11
12# O tema Typo requer configurações adicionais
13# Consulte a documentação oficial para detalhes específicos
14
15
16# Para executar o blog localmente
17hugo server --disableFastRender -D

Pipeline de CI/CD #

Para o processo de deploy, pode-se utilizar um processo simples de build e publicação do blog em um único repositório. O exemplo abaixo é um workflow do GitHub Actions que automatiza esse processo:

 1name: Deploy Hugo site to Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6
 7  workflow_dispatch:
 8
 9permissions:
10  contents: read
11  pages: write
12  id-token: write
13
14concurrency:
15  group: "pages"
16  cancel-in-progress: false
17
18defaults:
19  run:
20    shell: bash
21
22jobs:
23  build:
24    runs-on: ubuntu-latest
25    env:
26      HUGO_VERSION: 0.154.1
27    steps:
28      - name: Install Hugo CLI
29        run: |
30          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
31          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
32      - name: Install Dart Sass
33        run: sudo snap install dart-sass
34      - name: Checkout
35        uses: actions/checkout@v6
36        with:
37          submodules: recursive
38      - name: Setup Pages
39        id: pages
40        uses: actions/configure-pages@v5
41      - name: Build with Hugo
42        env:
43          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
44          HUGO_ENVIRONMENT: production
45        run: |
46          hugo --minify
47      - name: Upload artifact
48        uses: actions/upload-pages-artifact@v4
49        with:
50          path: ./public
51
52  deploy:
53    environment:
54      name: github-pages
55      url: ${{ steps.deployment.outputs.page_url }}
56    runs-on: ubuntu-latest
57    needs: build
58    steps:
59      - name: Deploy to GitHub Pages
60        id: deployment
61        uses: actions/deploy-pages@v4

Dificuldades #

1. Customização do tema: Como utilizei um tema oferecido pela comunidade, ele me ofereceu bastante agilidade na configuração inicial, no entanto realizar customizações foi um pouco desafiador, pois precisei entender a estrutura interna do tema escolhido para sobrepor alguns estilos e até mesmo reescrever algumas páginas.
2. Organização de conteúdo: O processo de organização da estrutura do projeto pode ser complexo, por enquanto optei por um sistema mais simples.

Melhorias #

Já realizei as seguintes customizações no blog comparado com o tema inicial:

1. Adição de foto na página inicial;
2. Listagem de sub-páginas (posts) na página inicial com limites;
3. Sistema para troca de temas (dark/light);
4. Suporte a multilinguagem;
   • Embora o Hugo já tenha um suporte nativo para i18n, foi necessário implementar um componente de troca de idiomas.
5. Animação no header.
6. Sumário lateral.

Além disso ainda tenho algumas ideias de melhorias que não foram implementadas:

1. Implementar um sistema de busca nativo no blog;
2. Adicionar um domínio customizado (migrar de brunoxd13.github.io);
3. Automatizar validação de ortografia e gramática nos posts.