Recentemente precisei personalizar a página inicial do meu blog Hugo que usa o tema PaperMod. O objetivo era criar uma homepage informativa que explicasse a organização do site e apresentasse os principais tópicos, sem a listagem automática de posts que o tema exibe por padrão.

Neste post, vou compartilhar os desafios encontrados e as soluções implementadas para ter controle total sobre o conteúdo da página inicial.

O Problema

O tema PaperMod oferece duas opções principais para a homepage:

  1. ProfileMode: Exibe um perfil com botões e informações básicas
  2. HomeInfoParams: Adiciona um bloco de informações antes da listagem de posts

Ambas as opções têm limitações:

  • O profileMode substitui completamente o conteúdo do arquivo _index.md
  • O homeInfoParams adiciona conteúdo extra, mas ainda lista os posts
  • Quando ambos estão desabilitados, o tema automaticamente lista todos os posts

A Solução: Template Personalizado

Para ter controle total sobre a homepage, implementei uma solução em três etapas:

1. Desabilitar o ProfileMode

Primeiro, desabilitei o profileMode no arquivo hugo.toml:

[params.profileMode]
  enabled = false  # era true
  title = "Brain Dump"
  subtitle = "Anotações, ideias, tópicos de estudos do dia a dia (e alguns devaneios)"

2. Remover HomeInfoParams

Em seguida, removi (ou comentei) a seção homeInfoParams para evitar conteúdo duplicado:

# [params.homeInfoParams]
#   Title = "Bem-vindo ao meu blog"
#   Content = "Aqui compartilho ideias, tutoriais e anotações direto do Obsidian."

3. Criar Template Personalizado

O principal aqui foi criar um template personalizado em layouts/index.html para sobrescrever o comportamento padrão do tema:

{{- define "main" }}

{{- if .Content }}
<div class="post-content">
  {{- if not (.Param "disableAnchoredHeadings") }}
  {{- partial "anchored_headings.html" .Content -}}
  {{- else }}{{ .Content }}{{ end }}
</div>
{{- end }}

{{- end }}{{- /* end main */ -}}

O template basicamente:

  • Renderiza apenas o conteúdo do arquivo _index.md
  • Mantém o processamento de markdown e âncoras nos títulos
  • Remove completamente a listagem automática de posts

(obrigado tio Gepeto pela ajuda nessas horas)

Criando o Conteúdo da Homepage

Com o template personalizado funcionando, tentei criar um arquivo content/_index.md que possa levantar o interesse:

---
title: "Brain (Hugo + Obsidian)"
description: "Blog pessoal e minhas anotações direto do Obsidian"
---

Este é meu espaço digital onde compartilho **conhecimento**, **experiências** e **reflexões** sobre tecnologia, carreira e desenvolvimento pessoal.

## Como o site está organizado

O conteúdo está estruturado de forma a facilitar sua navegação e descoberta de informações relevantes:

### 📝 **Blog**

Artigos estruturados e tutoriais completos sobre diversos temas técnicos...

### 🧠 **Brain**

Minhas anotações pessoais, importadas diretamente do Obsidian...

### 🏷️ **Tags**

Sistema de etiquetas para encontrar conteúdo específico rapidamente (assim espero)...

## Principais tópicos abordados (ou que eu gostaria de conseguir abordar)

### 🌩️ **Cloud Computing**
### 🗄️ **Banco de Dados**
### 🎓 **Certificações**
### 💼 **Carreira**
### 📊 **Business Intelligence**
### ⚙️ **DevOps**

## Sobre mim

Sou **Logan Merazzi**, profissional de tecnologia...

Problemas de Formatação Markdown

Durante a implementação, encontrei alguns problemas de formatação que precisaram ser corrigidos:

Linter Markdown

O linter identificou vários problemas:

  • Títulos duplicados (H1 no frontmatter e no conteúdo)
  • Espaços em branco desnecessários
  • Falta de linhas em branco ao redor de títulos e listas

Correções Aplicadas

(notem o espaçamento entre as linhas…)

# Antes (problemático)
### 📝 **Blog** 
Artigos estruturados...
- Item 1
- Item 2

# Depois (correto)
### 📝 **Blog**

Artigos estruturados...

- Item 1
- Item 2

Resultado Final

Por mim, acho que consegui terminar com uma homepage bem personalizada, onde:

  • Exibe apenas o conteúdo desejado do arquivo _index.md
  • Explica a organização do site de forma clara e estruturada
  • Apresenta os principais tópicos com emojis e descrições
  • Inclui seção “Sobre mim” com links sociais
  • Remove a listagem automática de posts da homepage
  • Mantém a formatação markdown adequada

Lições Aprendidas

  1. Templates personalizados: Criar um layouts/index.html personalizado oferece controle total sobre a homepage

  2. Entender a hierarquia de templates: Hugo segue uma ordem específica para escolher templates, e arquivos locais sempre sobrescrevem os do tema

  3. Formatação markdown importa: Problemas de formatação podem afetar a renderização, especialmente se o linters estiver “rigoroso” demais

  4. Documentar é essencial: Manter registro das alterações facilita manutenção futura e compartilhamento de conhecimento. Ainda mais agora, com a chegada forte da IA. Ter tudo bem documentado ajuda demais ela a entender todo o contexto de forma bem mais fácil, rápida e mais barata (aqui, tenho as minhas dúvidas)

Conclusão

Para personalizar a homepage do Hugo com tema PaperMod, é preciso entender muito como o tema funciona internamente e tem que estar muito disposto a criar novos templates personalizados quando necessário.

Se você está enfrentando limitações similares com temas Hugo, considere esta abordagem de templates personalizados - ela pode ser a chave para ter o controle total que você precisa.

💡 Life saving tip: Sempre teste suas alterações localmente antes de fazer deploy, e mantenha backups das configurações originais para facilitar rollbacks se necessário. Ou então, considere uma forma de deploy que te permita validar as alterações antes de aplicar