Instalação

Simplesmente siga o procedimento padrão do Hugo Início Rápido para começar rapidamente.

Instruções detalhadas de instalação podem ser encontradas abaixo. Instruções para atualizar o tema também estão disponíveis.

Skill para agentes

#

O Blowfish inclui uma skill para agentes que ensina agentes de programação com IA — como o Claude Code — a instalar, configurar e criar sites com o tema. Se utilizar um agente para trabalhar no seu site, instale a skill para que este conheça os ficheiros de configuração, os layouts, o front matter e os shortcodes do Blowfish.

Instale-a a partir do marketplace de plugins do Blowfish no Claude Code:

/plugin marketplace add nunocoracao/blowfish
/plugin install blowfish@blowfish

Em alternativa, copie a pasta da skill para o repositório do seu site em .claude/skills/blowfish/ — os agentes carregam automaticamente as skills guardadas no diretório .claude/skills/ de um projeto.

Instalação

#

Estas instruções irão ajudá-lo a começar com Hugo e Blowfish a partir de um estado completamente vazio. A maioria das dependências mencionadas neste guia pode ser instalada utilizando o gestor de pacotes da sua escolha para a sua plataforma.

Instalar Hugo

#

Se nunca utilizou Hugo antes, precisará de instalá-lo na sua máquina local. Pode verificar se já está instalado executando o comando hugo version.

Pode encontrar instruções de instalação detalhadas para a sua plataforma na documentação do Hugo.

Blowfish Tools

#

Acabámos de lançar uma nova ferramenta CLI para o ajudar a começar com o Blowfish. Irá criar um novo projeto Hugo, instalar o tema e configurar os ficheiros de configuração do tema por si. Ainda está em beta, por isso reporte quaisquer problemas que encontrar.

Instale a ferramenta CLI globalmente utilizando npm (ou outro gestor de pacotes):

npx blowfish-tools

ou

npm i -g blowfish-tools

Em seguida, execute o comando blowfish-tools para iniciar uma execução interativa que o guiará através dos casos de uso de criação e configuração.

blowfish-tools

Também pode executar o comando blowfish-tools new para criar um novo projeto Hugo e instalar o tema de uma só vez. Consulte a ajuda do CLI para mais informações.

blowfish-tools new mynewsite

Aqui está um vídeo curto de quão rápido é começar com o Blowfish utilizando a ferramenta CLI:

Instalação sem CLI

#

Criar um novo site

#

Execute o comando hugo new site mywebsite para criar um novo site Hugo num diretório chamado mywebsite.

Note que pode nomear o diretório do projeto como quiser, mas as instruções abaixo assumem que se chama mywebsite. Se utilizar um nome diferente, certifique-se de o substituir adequadamente.

Transferir o tema Blowfish

#

Existem várias formas diferentes de instalar o tema Blowfish no seu site Hugo. Da mais fácil para a mais difícil de instalar e manter, são:

• Submódulo Git (recomendado)
• Módulo Hugo
• Cópia manual de ficheiros

Se não tem a certeza, escolha o método do submódulo Git.

Instalação com Git

#

Este método é o mais rápido e fácil para manter o tema atualizado. Além do Hugo e Go, também precisará de garantir que o Git está instalado na sua máquina local.

Mude para o diretório do seu site Hugo (que criou acima), inicialize um novo repositório git e adicione o Blowfish como submódulo.

cd mywebsite
git init
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

Em seguida, continue para configurar os ficheiros de configuração do tema.

Instalação com Hugo

#

Para este método, utilizará o Hugo para gerir os seus temas. O Hugo utiliza Go para inicializar e gerir módulos, por isso certifique-se de ter o go instalado antes de prosseguir.

1. Transfira e instale o Go. Pode verificar se já está instalado utilizando o comando go version.

   Certifique-se de que está a utilizar Go versão 1.12 ou posterior, pois o Hugo exige isto para que os módulos funcionem corretamente.

2. A partir do diretório do seu projeto Hugo (que criou acima), inicialize os módulos para o seu site:

   # Se está a gerir o seu projeto no GitHub
   hugo mod init github.com/<username>/<repo-name>
   
   # Se está a gerir o seu projeto localmente
   hugo mod init my-project

3. Adicione o tema à sua configuração criando um novo ficheiro config/_default/module.toml e adicionando o seguinte:

   [[imports]]
   disable = false
   path = "github.com/nunocoracao/blowfish/v3"

4. Inicie o seu servidor utilizando hugo server e o tema será transferido automaticamente.

5. Continue para configurar os ficheiros de configuração do tema.

Instalação manual

#

1. Transfira a versão mais recente do código-fonte do tema.

   Transferir do Github

2. Extraia o arquivo, renomeie a pasta para blowfish e mova-a para o diretório themes/ dentro da pasta raiz do seu projeto Hugo.

3. Continue para configurar os ficheiros de configuração do tema.

Configurar ficheiros de configuração do tema

#

Na pasta raiz do seu site, elimine o ficheiro hugo.toml que foi gerado pelo Hugo. Copie os ficheiros de configuração *.toml do tema para a sua pasta config/_default/. Isto garantirá que tem todas as configurações corretas do tema e permitirá personalizar facilmente o tema de acordo com as suas necessidades.

Dependendo de como instalou o tema, encontrará os ficheiros de configuração do tema em locais diferentes:

• Módulos Hugo: No diretório de cache do Hugo, ou transfira uma cópia do GitHub
• Submódulo Git ou instalação manual: themes/blowfish/config/_default

Depois de copiar os ficheiros, a sua pasta de configuração deve ficar assim:

config/_default/
├─ hugo.toml
├─ languages.en.toml
├─ markup.toml
├─ menus.en.toml
├─ module.toml  # se instalou utilizando Módulos Hugo
└─ params.toml

Próximos passos

#

A instalação básica do Blowfish está agora completa. Continue para a secção Primeiros Passos para saber mais sobre a configuração do tema.

Instalar atualizações

#

De tempos a tempos, novas versões serão publicadas que aplicam correções e adicionam novas funcionalidades ao tema. Para tirar partido destas alterações, precisará de atualizar os ficheiros do tema no seu site.

Como fará isto dependerá do método de instalação que escolheu quando o tema foi originalmente instalado. Instruções para cada método podem ser encontradas abaixo.

• Submódulo Git
• Módulo Hugo
• Cópia manual de ficheiros

Atualização com Git

#

Submódulos Git podem ser atualizados utilizando o comando git. Simplesmente execute o seguinte comando e a versão mais recente do tema será transferida para o seu repositório local:

git submodule update --remote --merge

Depois de o submódulo ser atualizado, reconstrua o seu site e verifique se tudo funciona como esperado.

Atualização com Hugo

#

O Hugo torna a atualização de módulos super fácil. Simplesmente mude para o diretório do seu projeto e execute o seguinte comando:

hugo mod get -u

O Hugo atualizará automaticamente quaisquer módulos necessários para o seu projeto. Faz isto inspecionando os seus ficheiros module.toml e go.mod. Se tiver problemas com a atualização, verifique se estes ficheiros ainda estão configurados corretamente.

Em seguida, simplesmente reconstrua o seu site e verifique se tudo funciona como esperado.

Atualização manual

#

Atualizar o Blowfish manualmente requer que transfira a cópia mais recente do tema e substitua a versão antiga no seu projeto.

1. Transfira a versão mais recente do código-fonte do tema.

   Transferir do Github

2. Extraia o arquivo, renomeie a pasta para blowfish e mova-a para o diretório themes/ dentro da pasta raiz do seu projeto Hugo. Precisará de sobrescrever o diretório existente para substituir todos os ficheiros do tema.

3. Reconstrua o seu site e verifique se tudo funciona como esperado.

Atualizar da v2 para a v3

#

O Blowfish v3 é totalmente retrocompatível com sites v2: todas as novidades são opcionais, nenhuma opção de configuração foi removida e nenhum template ou partial foi renomeado. O seu site terá o mesmo aspeto e comportamento após a atualização, até ativar as novas funcionalidades.

• Submódulo Git: atualize como habitualmente — git submodule update --remote --merge. Não é necessário mais nada.
• Módulo Hugo: edite config/_default/module.toml e altere o caminho de importação de github.com/nunocoracao/blowfish/v2 para github.com/nunocoracao/blowfish/v3; depois execute hugo mod get -u.
• Instalação manual: transfira a última versão e substitua a pasta do tema, como descrito acima.

Após atualizar, consulte a documentação de configuração para conhecer as novas opções — o header flutuante, o layout landing, o fundo global, a barra de progresso de leitura e mais.