Personalização avançada

Existem muitas maneiras de fazer alterações avançadas no Blowfish. Leia abaixo para saber mais sobre o que pode ser personalizado e a melhor forma de alcançar o resultado desejado.

Se precisar de mais orientação, poste suas perguntas nas GitHub Discussions.

Estrutura do projeto Hugo

#

Antes de começar, primeiro uma nota rápida sobre a estrutura do projeto Hugo e as melhores práticas para gerenciar seu conteúdo e personalizações do tema.

O Blowfish foi construído para aproveitar todas as práticas padrão do Hugo. Ele é projetado para permitir que todos os aspectos do tema sejam personalizados e substituídos sem alterar nenhum dos arquivos principais do tema. Isso permite uma experiência de atualização perfeita enquanto oferece controle total sobre a aparência e o funcionamento do seu site.

Para conseguir isso, você nunca deve ajustar manualmente nenhum dos arquivos do tema diretamente. Seja instalando usando módulos Hugo, como um submódulo git ou incluindo manualmente o tema no seu diretório themes/, você deve sempre deixar esses arquivos intactos.

A maneira correta de ajustar qualquer comportamento do tema é substituindo arquivos usando a poderosa ordem de busca de arquivos do Hugo. Em resumo, a ordem de busca garante que quaisquer arquivos que você incluir no diretório do seu projeto terão automaticamente precedência sobre quaisquer arquivos do tema.

Por exemplo, se você quisesse substituir o template principal de artigo no Blowfish, você pode simplesmente criar seu próprio arquivo layouts/_default/single.html e colocá-lo na raiz do seu projeto. Este arquivo então substituirá o single.html do tema sem nunca alterar o tema em si. Isso funciona para qualquer arquivo do tema - templates HTML, partials, shortcodes, arquivos de configuração, dados, assets, etc.

Enquanto você seguir esta prática simples, você sempre poderá atualizar o tema (ou testar diferentes versões do tema) sem se preocupar em perder nenhuma de suas alterações personalizadas.

Alterar configurações de otimização de imagem

#

Hugo tem vários métodos integrados para redimensionar, cortar e otimizar imagens.

Como exemplo - em layouts/partials/article-link/card.html, você tem o seguinte código:

{{ with .Resize "600x" }}
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
{{ end }}

O comportamento padrão do Hugo aqui é redimensionar a imagem para 600px mantendo a proporção.

Vale notar que as configurações de imagem padrão como o ponto de ancoragem também podem ser definidas na sua configuração do site assim como no próprio template.

Veja os docs do Hugo sobre processamento de imagens para mais informações.

Esquemas de cores

#

O Blowfish vem com vários esquemas de cores prontos para usar. Para alterar o esquema de cores básico, você pode definir o parâmetro do tema colorScheme. Consulte a seção Primeiros passos para saber mais sobre os esquemas integrados.

Além dos esquemas padrão, você também pode criar os seus próprios e re-estilizar todo o site ao seu gosto. Os esquemas são criados colocando um arquivo <nome-do-esquema>.css na pasta assets/css/schemes/. Uma vez criado o arquivo, simplesmente referencie-o pelo nome na configuração do tema.

O Blowfish define uma paleta de três cores que é usada em todo o tema. As três cores são definidas como variantes neutral, primary e secondary, cada uma contendo dez tons de cor.

Devido à forma como o Tailwind CSS 3.0 calcula os valores de cor com opacidade, as cores especificadas no esquema precisam conformar-se a um formato particular fornecendo os valores de cor vermelho, verde e azul.

:root {
  --color-primary-500: 139, 92, 246;
}

Este exemplo define uma variável CSS para a cor primary-500 com um valor vermelho de 139, valor verde de 92 e valor azul de 246.

Use uma das folhas de estilo do tema existentes como modelo. Você é livre para definir suas próprias cores, mas para inspiração, confira a referência da paleta de cores do Tailwind oficial.

Substituir a folha de estilos

#

Às vezes você precisa adicionar um estilo personalizado para estilizar seus próprios elementos HTML. O Blowfish prevê este cenário permitindo que você substitua os estilos padrão na sua própria folha de estilos CSS. Simplesmente crie um arquivo custom.css na pasta assets/css/ do seu projeto.

O arquivo custom.css será minificado pelo Hugo e carregado automaticamente após todos os outros estilos do tema, o que significa que qualquer coisa no seu arquivo personalizado terá precedência sobre os padrões.

Usar fontes adicionais

#

O Blowfish permite que você altere facilmente a fonte do seu site. Após criar um arquivo custom.css na pasta assets/css/ do seu projeto, coloque seu arquivo de fonte dentro de uma pasta fonts na pasta raiz static.

.
├── assets
│   └── css
│       └── custom.css
...
└─── static
    └── fonts
        └─── font.ttf

Isso torna a fonte disponível para o site. Agora, a fonte pode simplesmente ser importada no seu custom.css e substituída onde você achar melhor. O exemplo abaixo mostra como seria substituir a fonte para todo o html.

@font-face {
    font-family: font;
    src: url('/fonts/font.ttf');
}

html {
    font-family: font;
}

Ajustar o tamanho da fonte

#

Alterar o tamanho da fonte do seu site é um exemplo de substituição da folha de estilos padrão. O Blowfish torna isso simples pois usa tamanhos de fonte escalados em todo o tema que são derivados do tamanho da fonte HTML base. Por padrão, o Tailwind define o tamanho padrão como 12pt, mas pode ser alterado para qualquer valor que você preferir.

Crie um arquivo custom.css usando as instruções acima e adicione a seguinte declaração CSS:

/* Aumentar o tamanho de fonte padrão */
html {
  font-size: 13pt;
}

Simplesmente alterando este único valor, todos os tamanhos de fonte no seu site serão ajustados para corresponder a este novo tamanho. Portanto, para aumentar os tamanhos de fonte gerais usados, faça o valor maior que 12pt. Da mesma forma, para diminuir os tamanhos de fonte, faça o valor menor que 12pt.

Alterar o tema de destaque de sintaxe

#

Para alterar o tema de destaque de sintaxe, crie assets/css/custom.css e adicione o seguinte:

.chroma,
.chroma *,
.chroma:is(.dark *),
.chroma:is(.dark *) * {
  color: unset;
  font-weight: unset;
  font-style: unset;
}

Isso limpa os estilos padrão do Chroma. O próximo passo é incorporar os estilos do Chroma no seu arquivo CSS usando o comando hugo gen chromastyles:

# Mac/Linux
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css

# Windows PowerShell
# Este comando não pode ser executado no CMD; deve ser executado no PowerShell
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"

Veja todos os estilos disponíveis na documentação do Hugo.

Construir o CSS do tema a partir da fonte

#

Se você quiser fazer uma alteração maior, pode aproveitar o compilador JIT do Tailwind CSS e reconstruir todo o CSS do tema do zero. Isso é útil se você quiser ajustar a configuração do Tailwind ou adicionar classes extras do Tailwind à folha de estilos principal.

Vamos ver como funciona a construção do Tailwind CSS.

Configuração do Tailwind

#

Para gerar um arquivo CSS que contenha apenas as classes do Tailwind que estão realmente sendo usadas, o compilador JIT precisa escanear todos os templates HTML e arquivos de conteúdo Markdown para verificar quais estilos estão presentes no markup. O compilador faz isso olhando o arquivo tailwind.config.js que está incluído na raiz do diretório do tema:

// themes/blowfish/tailwind.config.js

module.exports = {
  content: [
    "./layouts/**/*.html",
    "./content/**/*.{html,md}",
    "./themes/blowfish/layouts/**/*.html",
    "./themes/blowfish/content/**/*.{html,md}",
  ],

  // e mais...
};

Esta configuração padrão foi incluída com esses caminhos de conteúdo para que você possa facilmente gerar seu próprio arquivo CSS sem precisar modificá-la, desde que siga uma estrutura de projeto particular. Ou seja, você tem que incluir o Blowfish no seu projeto como um subdiretório em themes/blowfish/. Isso significa que você não pode facilmente usar os módulos Hugo para instalar o tema e deve optar pela instalação por submódulo git (recomendado) ou instalação manual. Os docs de instalação explicam como instalar o tema usando qualquer um desses métodos.

Estrutura do projeto

#

Para aproveitar a configuração padrão, seu projeto deve se parecer com algo assim…

.
├── assets
│   └── css
│       └── compiled
│           └── main.css  # este é o arquivo que vamos gerar
├── config  # config do site
│   └── _default
├── content  # conteúdo do site
│   ├── _index.md
│   ├── projects
│   │   └── _index.md
│   └── blog
│       └── _index.md
├── layouts  # layouts personalizados para seu site
│   ├── partials
│   │   └── extend-article-link/simple.html
│   ├── projects
│   │   └── list.html
│   └── shortcodes
│       └── disclaimer.html
└── themes
    └── blowfish  # submódulo git ou instalação manual do tema

Esta estrutura de exemplo adiciona um novo tipo de conteúdo projects com seu próprio layout personalizado junto com um shortcode personalizado e partial estendido. Desde que o projeto siga esta estrutura, tudo o que é necessário é recompilar o arquivo main.css.

Instalar dependências

#

Para que isso funcione, você precisará mudar para o diretório themes/blowfish/ e instalar as dependências do projeto. Você precisará do npm na sua máquina local para esta etapa.

cd themes/blowfish
npm install

Executar o compilador do Tailwind

#

Com as dependências instaladas, tudo o que resta é usar o Tailwind CLI para invocar o compilador JIT. Navegue de volta para a raiz do seu projeto Hugo e execute o seguinte comando:

cd ../..
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit

É um comando um pouco feio devido aos caminhos envolvidos, mas essencialmente você está chamando o Tailwind CLI e passando a localização do arquivo de config do Tailwind (o que vimos acima), onde encontrar o arquivo main.css do tema e então onde você quer que o arquivo CSS compilado seja colocado (ele vai para a pasta assets/css/compiled/ do seu projeto Hugo).

O arquivo de config escaneará automaticamente todo o conteúdo e layouts no seu projeto assim como todos os do tema e construirá um novo arquivo CSS que contém todo o CSS necessário para seu site. Devido à forma como o Hugo lida com a hierarquia de arquivos, este arquivo no seu projeto agora substituirá automaticamente o que vem com o tema.

Cada vez que você fizer uma alteração nos seus layouts e precisar de novos estilos do Tailwind CSS, você pode simplesmente executar o comando novamente e gerar o novo arquivo CSS. Você também pode adicionar -w ao final do comando para executar o compilador JIT em modo watch.

Criar um script de build

#

Para completar totalmente esta solução, você pode simplificar todo este processo adicionando aliases para estes comandos, ou fazer o que eu faço e adicionar um package.json à raiz do seu projeto que contenha os scripts necessários…

// package.json

{
  "name": "my-website",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "server": "hugo server -b http://localhost -p 8000",
    "dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
    "build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
  },
  // e mais...
}

Agora quando você quiser trabalhar no design do seu site, pode invocar npm run dev e o compilador será executado em modo watch. Quando estiver pronto para implantar, execute npm run build e você terá um build limpo do Tailwind CSS.

🙋‍♀️ Se precisar de ajuda, sinta-se à vontade para fazer uma pergunta nas GitHub Discussions.