Configuração de Variáveis por Ambiente no Hugo

Uma das necessidades comuns em projetos web é ter configurações diferentes dependendo do ambiente em que o site está sendo executado (desenvolvimento, produção, local, etc.). No Hugo, podemos implementar essa funcionalidade de forma elegante usando variáveis condicionais e templates personalizados.

Este guia explica como configurar URLs dinâmicas que mudam com base no ambiente, como por exemplo, fazer com que um link aponte para /posts em ambiente local e para https://blog.merazzi.com.br em produção.

Estrutura da Solução

Nossa solução consiste em três componentes principais:

  1. Configuração no arquivo hugo.toml
  2. Arquivo parcial para processar URLs dinâmicas
  3. Template personalizado que usa o parcial

1. Configuração no arquivo hugo.toml

No arquivo principal de configuração do Hugo, adicionamos:

[params]
  env = "production" # opções: "production", "development", "local"
  
  # URLs específicas por ambiente
  [params.url]
    blog = "/posts" # valor padrão para ambiente local

A variável params.env define o ambiente atual, e a seção params.url contém os valores padrão para cada URL dinâmica (usados principalmente no ambiente local).

2. Arquivo Parcial para URLs Dinâmicas

Criamos um arquivo parcial em layouts/partials/env-url.html que processa as URLs com base no ambiente:

{{- /* env-url.html: Retorna URLs baseadas no ambiente atual */ -}}
{{- $url := .url -}}
{{- $env := site.Params.env -}}

{{- if eq $url "blog" -}}
  {{- if eq $env "production" -}}
    https://blog.merazzi.com.br
  {{- else if eq $env "development" -}}
    https://blog.merazzi.com.br
  {{- else -}}
    {{- site.Params.url.blog -}}
  {{- end -}}
{{- else -}}
  {{- $url -}}
{{- end -}}

Este arquivo recebe uma URL como entrada e retorna a versão apropriada com base no ambiente atual.

3. Template Personalizado

Para usar nosso sistema de URLs dinâmicas, sobrescrevemos o template do tema que renderiza os botões. No nosso caso, criamos layouts/partials/index_profile.html com a seguinte modificação na seção de botões:

{{- with .buttons }}
<div class="buttons">
    {{- range . }}
    {{- $dynamicUrl := dict "url" .url | partial "env-url.html" -}}
    <a class="button" href="{{ trim $dynamicUrl " " }}" rel="noopener" title="{{ .name }}">
        <span class="button-inner">
            {{ .name }}
            {{- if (findRE "://" $dynamicUrl) }}&nbsp;
            <svg fill="none" shape-rendering="geometricPrecision" stroke="currentColor" stroke-linecap="round"
                stroke-linejoin="round" stroke-width="2.5" viewBox="0 0 24 24" height="14" width="14">
                <path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6"></path>
                <path d="M15 3h6v6"></path>
                <path d="M10 14L21 3"></path>
            </svg>
            {{- end }}
        </span>
    </a>
    {{- end }}
</div>
{{- end }}

A linha chave é {{- $dynamicUrl := dict "url" .url | partial "env-url.html" -}}, que passa a URL do botão para nosso parcial e usa o resultado como o href do link.

Como Usar

Alternando Entre Ambientes

Para alternar entre ambientes, simplesmente mude o valor de params.env no arquivo hugo.toml:

[params]
  env = "production"  # ou "development" ou "local"

Adicionando Novas URLs Dinâmicas

Para adicionar uma nova URL dinâmica:

  1. Adicione o valor padrão em [params.url] no arquivo hugo.toml:
[params.url]
  blog = "/posts"
  api = "/api/local"  # nova URL dinâmica
  1. Atualize o arquivo layouts/partials/env-url.html para incluir a lógica para a nova URL:
{{- if eq $url "blog" -}}
  <!-- lógica existente -->
{{- else if eq $url "api" -}}
  {{- if eq $env "production" -}}
    https://api.merazzi.com.br
  {{- else if eq $env "development" -}}
    https://dev-api.merazzi.com.br
  {{- else -}}
    {{- site.Params.url.api -}}
  {{- end -}}
{{- else -}}
  {{- $url -}}
{{- end -}}

Usando URLs Dinâmicas em Outros Templates

Para usar URLs dinâmicas em outros templates ou arquivos de conteúdo:

{{ $dynamicUrl := dict "url" "blog" | partial "env-url.html" }}
<a href="{{ $dynamicUrl }}">Link para o Blog</a>

Configurações Avançadas

Arquivos de Configuração por Ambiente

Além de usar a variável params.env, o Hugo também suporta arquivos de configuração específicos por ambiente:

  1. hugo.toml - configuração base
  2. hugo.development.toml - configuração específica para desenvolvimento
  3. hugo.production.toml - configuração específica para produção

Para usar um arquivo de configuração específico:

hugo server --config hugo.development.toml
# ou
hugo --config hugo.production.toml

Variáveis de Ambiente

Outra abordagem é usar variáveis de ambiente para controlar o comportamento do Hugo:

HUGO_ENV=production hugo

E então verificar o valor em seus templates:

{{ if eq (getenv "HUGO_ENV") "production" }}
  <!-- código específico para produção -->
{{ else }}
  <!-- código para outros ambientes -->
{{ end }}

Conclusão

Com esta implementação, você tem um sistema flexível para definir URLs e outras configurações específicas por ambiente no seu site Hugo. Isso facilita o desenvolvimento e teste em diferentes ambientes sem precisar modificar manualmente várias partes do código.

Esta abordagem pode ser estendida para outras configurações além de URLs, como chaves de API, configurações de análise, ou qualquer outro valor que precise mudar entre ambientes.