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 passo crucial foi criar um template personalizado em layouts/index.html que sobrescreve 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 */ -}}

Este template simples:

  • 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

Criando o Conteúdo da Homepage

Com o template personalizado funcionando, criei um arquivo content/_index.md rico em conteúdo:

---
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...

## Principais tópicos abordados

### 🌩️ **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

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

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

Artigos estruturados...

- Item 1
- Item 2

Resultado Final

A solução resultou em uma homepage completamente personalizada que:

✅ 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 são poderosos: 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 com linters rigorosos

  4. Documentar é essencial: Manter registro das alterações facilita manutenção futura e compartilhamento de conhecimento

Conclusão

Personalizar a homepage do Hugo com tema PaperMod requer entender como o tema funciona internamente e estar disposto a criar templates personalizados quando necessário.

A solução apresentada oferece máxima flexibilidade mantendo a compatibilidade com o tema, permitindo atualizações futuras sem perder as customizações.

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 sobre seu site.

💡 Dica: Sempre teste suas alterações localmente antes de fazer deploy, e mantenha backups das configurações originais para facilitar rollbacks se necessário.