[pt-BR] Hugo: Criando sua primeira aplicação

No artigo anterior dessa série, falei um pouco sobre o que me levou a conhecer o Hugo, o que essa ferramenta é e algumas de suas features. Agora, quero mostrar como você pode criar sua primeira aplicação usando esse framework, e o quão fácil é fazer isso.

Configuração de ambiente

O primeiro passo para criar uma aplicação com o Hugo é, obviamente, ter o Hugo instalado. Para fazer isso, você pode visitar o site oficial do Hugo (gohugo.io), e acessar a sessão de downloads. Lá, você verá instruções específicas para a instalação desse framework no seu sistema operacional, seja ele Windows, MacOS ou alguma distribuição Linux.

Depois de fazer o processo de instalação descrito na documentação da ferramenta, você pode rodar o comando hugo --version no seu terminal, e se o resultado for uma versão do Hugo, isso significa que a instalação foi um sucesso.

⚙️ Criando o projeto

Vamos agora fazer a criação de um projeto com o Hugo e colocá-lo para rodar. Nessa etapa, vamos usar o terminal e quem usa Windows, precisa se atentar para um aviso da documentação do Hugo, que fala que os comandos a seguir devem ser rodados no PowerShell ou em um terminal Linux, como WSL ou Git Bash.

Dito isso, podemos fazer a criação do nosso site, ou seja, do nosso projeto Hugo. Para isso, basta rodar o comando hugo new site novo-site, onde novo-site é o nome que você quer dar ao projeto. O processo de criação de um projeto Hugo criará uma pasta com o nome novo-site com alguns arquivos de configuração do projeto que abordarei com mais detalhes no próximo tópico.

📁 Estrutura de pastas

Agora que já criamos o projeto, vamos entender como é a estrutura de pastas de projeto Hugo, e o que ela representa. Uma estrutura de pastas do Hugo se parece com a imagem abaixo:

E aqui está um breve resumo do que cada uma delas representa:

• archetypes: Pasta onde definimos modelos que serão usados para a criação de conteúdos dentro do site.

• content: Pasta que armazena o conteúdo do seu site.

• data: Armazena arquivos que podem ser usados para injetar conteúdo dinâmico na aplicação.

• themes: Pasta onde os temas da sua aplicação são armazenados. Esses temas são responsáveis pela formatação visual da sua aplicação.

• layouts: Essa pasta contém modelos de partes do layout do página que irão sobrescrever os modelos existentes no tema. Se você tiver um tema instalado, não precisa se preocupar com essa página, a menos que você queira alterar algum dos arquivos de configuração do tema.

• static: Arquivos estáticos que ficarão disponíveis para o site, como imagens.

• config.toml ou hugo.toml: O arquivo de configuração do Hugo, onde são definidos parâmetros e variáveis da aplicação e também do tema.

🖌️ Inserindo um tema

Temas são conjuntos de arquivos que definem toda a estrutura visual do site. Existem vários temas diferentes para propósitos diferentes que você pode escolher colocar na sua aplicação. Uma lista completa desses temas pode ser acessada clicando aqui.

Para adicionar um tema na aplicação, precisaremos criar uma pasta dentro de themes para armazenar o tema, que comumente é nomeada com o mesmo nome do tema. Após criada essa pasta, basta adicionar dentro dela o conteúdo do repositório do GitHub que contém esse tema, que normalmente é acessível a partir do botão de Download na página do tema. Esse processo pode ser feito manualmente, mas utilizarei uma outra abordagem com os submódulos do Git.

Dentro do Git, um submódulo é um repositório adicionado dentro de outro, e meu objetivo aqui é adicionar o repositório do tema como submódulo ao meu site. Para isso, preciso fazer com que meu site seja um repositório do Git, o que pode ser feito com o comando git init e depois adicionar como submódulo o tema do projeto.

Para esse exemplo, utilizarei o tema flat*, e para adicioná-lo como submódulo, basta rodar o comando git submodule add https://github.com/leafee98/hugo-theme-flat.git themes/flat. Esse comando vai adicionar o repositório do tema como um submódulo no repositório atual, armazenando-o dentro da pasta themes/flat.

Depois de adicionar o tema do projeto (seja usando Git, ou não), é preciso adicionar o tema no arquivo de configuração. Para isso, adicione uma linha de texto com o código theme = 'flat' no arquivo hugo.toml e pronto, seu tema já estará aplicado. Vale lembrar aqui que o nome que será associado ao tema, deve ser o mesmo nome da pasta onde o tema foi salvo dentro de layouts.

Com isso, terminamos a configuração básica do projeto. Agora as coisas começam a ficar divertidas.

🗒️ Adicionando conteúdo

Para adicionar conteúdo no site, você deve digitar o comando hugo new content nome-conteudo.extensao. O nome do conteúdo pode ser qualquer coisa, já a extensão deve ser algo como md ou html. Eu criarei um arquivo chamado teste com o comando hugo new content teste.md.

Esse comando irá criar um novo arquivo de conteúdo na pasta content, que possuirá algumas linhas já preenchidas, como as mostradas abaixo:

+++
title = 'Teste'
date = 2024-05-26T10:13:13-03:00
draft = true
+++

Essas linhas têm alguns metadados que são referentes ao conteúdo que você acabou de criar, como o título (que é derivado do nome do arquivo), a data de criação, e se a página é um rascunho ou não. Por padrão, páginas marcadas como rascunho não são renderizadas pelo servidor, a menos que ele seja iniciado com uma flag para sinalizar isso.

Essas linhas de configuração são chamadas de front matter e são definidas dentro do arquivo archetype/default.md, que é um arquivo com a estrutura padrão do front matter para arquivos do tipo markdown. Isso quer dizer que sempre que você criar um novo arquivo markdown, ele usará por padrão a estrutura definida em archetype/default. Você pode criar diferentes archetypes para servirem de modelo para diferentes tipos de páginas, mas para isso será preciso estudar um pouco mais a fundo como esses arquivos são estruturados. Por enquanto, o modelo padrão será o suficiente.

Agora que já temos o arquivo, podemos adicionar qualquer texto markdown após o front matter, e trocar o valor de draft para false. O meu arquivo ficou assim:

+++
title = 'Teste'
date = 2024-05-26T10:13:13-03:00
draft = false
+++

## Teste

Eu sou um teste

Depois disso, basta iniciar o servidor com hugo serve e sua aplicação já estará disponível. Porém, ao acessar a URL indicada no servidor, localhost:1313, você verá o tema, mas não a sua página de teste.

Isso acontece porque o diretório content equivale ao / da sua aplicação, e se você quiser acessar a página teste que está dentro de content, o caminho correto no navegador seria /teste, e de fato acessando essa url você consegue ver o conteúdo que definiu:

Prontinho, agora você acaba de criar a uma primeira página dentro de um site Hugo. Fácil, não é? Eu poderia terminar esse artigo por aqui, mas ainda existem algumas particularidades relacionadas ao tema que são extremamente importantes.

🎨 O que eu ainda não te contei sobre temas

Anteriormente eu falei que um tema o Hugo é responsável pelo aspecto visual da sua aplicação. Isso é verdade, mas eu acabei não mencionando que um tema também é responsável por alguns aspectos funcionais da sua aplicação. Se olharmos o catálogo de temas do Hugo, veremos que muitos deles são feitos para um tipo de aplicação específica, como o tema que escolhi para esse exemplo, é um tema de blog. Nesses casos, o tema já contém funcionalidades específicas para um blog, como um menu de categorias e tags e a possibilidade de exibir os últimos posts.

Cada tema tem particularidades específicas que podem estar relacionadas ao seu funcionamento, a sua estrutura de arquivos e até mesmo às possibilidades de personalização que podem ser feitas. Por isso, sempre recomendo que você dê uma olhada na documentação do tema que você escolheu para ter uma noção maior das possibilidades e eventuais regras internas que o tema tem.

Dito isso, vamos começar a estruturar melhor a nossa aplicação para parecer um blog. Para isso, vou criar dentro de content uma pasta posts com alguns posts. Para isso, vou usar os comandos hugo new content posts/post1.mde hugo new content posts/post2.md. Aqui é importante dizer que eu não preciso criar a pasta posts manualmente, já que ela será criada automaticamente pelo Hugo.

Cada um dos posts foi inicializado com um front matter igual ao do arquivo teste.md que criamos anteriormente, e aqui eu irei fazer algumas modificações extras, então além de trocar a propriedade draft para false também adicionarei algumas tags e uma categoria ao arquivo já que essas são propriedades que o meu tema especificamente usa para criar comportamentos de busca. Os posts ficarão mais ou menos assim:

+++
title = 'Post1'
date = 2024-05-26T10:41:33-03:00
draft = false
tags = [
    "tag1", "tag2", "tag3"
]
categories = [
    "categoria1"
]
+++

## Post1

Primeiro Post

Mantive mais ou menos a mesma estrutura para o post2, fazendo uma pequena alteração na categoria. Agora, essas páginas estarão acessíveis a partir de localhost:1313/posts/post1 e localhost:1313/posts/post2 respectivamente, porém não iremos acessá-las ainda, já que quero fazer uma configuração específica do tema para já mostrar esses posts na página inicial. Para isso, irei até o meu arquivo hugo.toml e adicionarei o seguinte código:

[params]
mainSections = ['posts']

Esse código é referente a uma configuração específica do tema, que trará o conteúdo da pasta posts para uma sessão principal na página inicial. E aproveitando que já estou mexendo no arquivo de configuração, também irei alterar o título da aplicação para "Meu Blog" e a língua para "pt-br". Esse arquivo ficará mais ou menos assim:

languageCode = 'pt-br'
title = 'Meu Blog'
theme= 'flat'

[params]
mainSections = ['posts']

Depois disso, basta acessar a página principal da aplicação e pronto. Nosso blog já está disponível e não só mostrando os posts, mas também listando as categorias e tags que adicionei nos arquivos.

⌛ Considerações finais

Nesse artigo mostrei como você pode criar um site utilizando Hugo. O processo em si é bem tranquilo e espero que você tenha conseguido acompanhá-lo. Também falei aqui sobre os temas do Hugo, e quero ressaltar a importância de entender o tema que você está utilizando na sua aplicação, pois entendendo bem o funcionamento do tema, você poderá tirar um proveito muito maior da estrutura e funcionalidades que já disponíveis na aplicação.

Té mais! 🧑‍💻