O Hugo é um gerador de sites estáticos conhecido por sua velocidade e flexibilidade. Embora seja excelente para conteúdo estático, muitas vezes queremos adicionar funcionalidades dinâmicas e interativas, como jogos, formulários ou visualizações de dados.

A solução mais elegante e poderosa no ecossistema Hugo para isso é o uso de Shortcodes.

O que são Shortcodes no Hugo? Link para o cabeçalho

Shortcodes são pequenos pedaços de código que você pode chamar diretamente dentro do seu conteúdo Markdown. Eles são essencialmente templates (arquivos .html ou .html com <script> e <style> inline) que o Hugo processa e injeta no lugar da chamada do Shortcode.

Eles permitem encapsular lógica HTML, CSS e JavaScript complexa e reutilizável, mantendo seu arquivo Markdown limpo e focado apenas no conteúdo.

1. O Exemplo: O Jogo da Memória Emoji Link para o cabeçalho

Vamos usar o “Jogo da Memória Emoji” que desenvolvemos como exemplo prático. Este jogo é um bloco de HTML, CSS e JavaScript completamente autônomo.

A Estrutura do Shortcode Link para o cabeçalho

Para que o Hugo reconheça o Shortcode, você deve salvar o código do jogo em um arquivo .html dentro do diretório de layouts do seu projeto:

1. Crie o diretório se ele não existir: layouts/shortcodes/
2. Crie o arquivo do Shortcode dentro dele: layouts/shortcodes/jogo_memoria.html

O conteúdo do Shortcode que criamos (o HTML completo com as tags <style> e <script> embutidas) é o que torna o jogo funcional de forma isolada.

2. Garantindo a Compatibilidade (O Segredo do CSS) Link para o cabeçalho

O principal desafio ao incorporar qualquer aplicação externa é o conflito de estilos (CSS) com o tema do seu blog.

No nosso caso, o jogo inicial utilizava o framework Tailwind CSS, que aplica um “reset” global (chamado Preflight) que, embora necessário para o Tailwind, quebrou a formatação padrão do seu texto (<p>, <h1>, etc.).

A Solução Ideal (Conforme Implementada):

Para garantir 100% de compatibilidade, a melhor prática é:

1. Evitar CDNs de CSS que injetam resets globais (como o Tailwind CDN).
2. Converter estilos de layout para CSS puro e isolado: Todo o CSS do jogo (layout, cores, animações 3D) foi movido para uma tag <style> dentro do Shortcode, usando classes com nomes únicos (.memory-game-wrapper, .game-button), garantindo que eles só afetem os elementos do jogo.

Dessa forma, o Shortcode atua como um widget independente que não interfere no restante da sua página.

3. Como Incorporar o Jogo em um Post Link para o cabeçalho

Depois de salvar o código no arquivo layouts/shortcodes/jogo_memoria.html, o uso é extremamente simples.

Basta abrir qualquer arquivo Markdown do seu post (.md) e inserir a chamada do Shortcode:

---
title: "Meu Post com Jogo Interativo"
date: 2024-12-14
---

Este é o início do meu artigo. Abaixo, vamos inserir o Jogo da Memória
que criamos usando o Shortcode.

{{< jogo_memoria >}}

Espero que os leitores gostem de uma pausa interativa!

Nota: A sintaxe {{< jogo_memoria >}} usa o nome do arquivo que você criou (jogo_memoria.html) sem a extensão.

Resumo dos Benefícios Link para o cabeçalho

Exemplo de shortcode do jogo Link para o cabeçalho

Espero que gostem!