Personalização avançada

Existem muitas formas de fazer alterações avançadas ao 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, publique as 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 gerir o seu conteúdo e personalizações do tema.

O Blowfish foi construído para aproveitar todas as práticas padrão do Hugo. Está concebido para permitir que todos os aspetos do tema sejam personalizados e substituídos sem alterar nenhum dos ficheiros principais do tema. Isto permite uma experiência de atualização perfeita enquanto oferece controlo total sobre a aparência e o funcionamento do seu website.

Para conseguir isto, nunca deve ajustar manualmente nenhum dos ficheiros do tema diretamente. Quer instale utilizando módulos Hugo, como um submódulo git ou incluindo manualmente o tema no seu diretório themes/, deve sempre deixar estes ficheiros intactos.

A forma correta de ajustar qualquer comportamento do tema é substituindo ficheiros utilizando a poderosa ordem de pesquisa de ficheiros do Hugo. Em resumo, a ordem de pesquisa garante que quaisquer ficheiros que inclua no diretório do seu projeto terão automaticamente precedência sobre quaisquer ficheiros do tema.

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

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

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

#

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

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

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

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

Vale notar que as configurações de imagem predefinidas 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 a utilizar. Para alterar o esquema de cores básico, pode definir o parâmetro do tema colorScheme. Consulte a secção Primeiros passos para saber mais sobre os esquemas integrados.

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

O Blowfish define uma paleta de três cores que é utilizada 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 de 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.

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

Substituir a folha de estilos

#

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

O ficheiro 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 ficheiro personalizado terá precedência sobre os valores predefinidos.

Utilizar tipos de letra adicionais

#

O Blowfish permite que altere facilmente o tipo de letra do seu site. Após criar um ficheiro custom.css na pasta assets/css/ do seu projeto, coloque o seu ficheiro de tipo de letra dentro de uma pasta fonts na pasta raiz static.

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

Isto torna o tipo de letra disponível para o website. Agora, o tipo de letra pode simplesmente ser importado no seu custom.css e substituído onde achar melhor. O exemplo abaixo mostra como seria substituir o tipo de letra para todo o html.

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

html {
    font-family: font;
}

Ajustar o tamanho do tipo de letra

#

Alterar o tamanho do tipo de letra do seu website é um exemplo de substituição da folha de estilos predefinida. O Blowfish torna isto simples pois utiliza tamanhos de tipo de letra escalados em todo o tema que são derivados do tamanho do tipo de letra HTML base. Por predefinição, o Tailwind define o tamanho predefinido como 12pt, mas pode ser alterado para qualquer valor que preferir.

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

/* Aumentar o tamanho de tipo de letra predefinido */
html {
  font-size: 13pt;
}

Simplesmente alterando este único valor, todos os tamanhos de tipo de letra no seu website serão ajustados para corresponder a este novo tamanho. Portanto, para aumentar os tamanhos de tipo de letra gerais utilizados, faça o valor maior que 12pt. Da mesma forma, para diminuir os tamanhos de tipo de letra, 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;
}

Isto limpa os estilos predefinidos do Chroma. O próximo passo é incorporar os estilos do Chroma no seu ficheiro CSS utilizando 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 quiser fazer uma alteração maior, pode aproveitar o compilador JIT do Tailwind CSS e reconstruir todo o CSS do tema do zero. Isto é útil se quiser ajustar a configuração do Tailwind ou adicionar classes extra do Tailwind à folha de estilos principal.

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

Configuração do Tailwind

#

Para gerar um ficheiro CSS que contenha apenas as classes do Tailwind que estão realmente a ser utilizadas, o compilador JIT precisa de analisar todos os templates HTML e ficheiros de conteúdo Markdown para verificar quais estilos estão presentes no markup. O compilador faz isto olhando para o ficheiro 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 predefinida foi incluída com estes caminhos de conteúdo para que possa facilmente gerar o seu próprio ficheiro CSS sem precisar de modificá-la, desde que siga uma estrutura de projeto particular. Ou seja, tem de incluir o Blowfish no seu projeto como um subdiretório em themes/blowfish/. Isto significa que não pode facilmente utilizar 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 utilizando qualquer um destes métodos.

Estrutura do projeto

#

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

.
├── assets
│   └── css
│       └── compiled
│           └── main.css  # este é o ficheiro 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 o 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 o seu próprio layout personalizado juntamente com um shortcode personalizado e partial estendido. Desde que o projeto siga esta estrutura, tudo o que é necessário é recompilar o ficheiro main.css.

Instalar dependências

#

Para que isto funcione, precisará de mudar para o diretório themes/blowfish/ e instalar as dependências do projeto. 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 é utilizar 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 está a chamar o Tailwind CLI e a passar-lhe a localização do ficheiro de config do Tailwind (o que vimos acima), onde encontrar o ficheiro main.css do tema e depois onde quer que o ficheiro CSS compilado seja colocado (vai para a pasta assets/css/compiled/ do seu projeto Hugo).

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

Cada vez que fizer uma alteração nos seus layouts e precisar de novos estilos do Tailwind CSS, pode simplesmente executar o comando novamente e gerar o novo ficheiro CSS. 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, 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 quiser trabalhar no design do seu site, pode invocar npm run dev e o compilador será executado em modo watch. Quando estiver pronto para implementar, execute npm run build e terá um build limpo do Tailwind CSS.

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