Mudando do WordPress para o Hugo

Quando o WordPress 5 foi lançado, fiquei empolgado em usar o editor Gutenberg para criar blocos personalizados, pois as postagens no meu blog pessoal tinham alguns recursos que eu poderia transformar em um bloco, facilitando a configuração do meu conteúdo. Era definitivamente uma coisa legal de se ter, mas ainda parecia bastante inchado.

Na mesma época, comecei a ler cada vez mais sobre geradores de sites estáticos e o JAMstack (este artigo de Chris Ferdinandi me convenceu). Com projetos paralelos pessoais, você pode descartar uma grande variedade de problemas, mas como profissional, você precisa garantir a melhor qualidade possível. Desempenho, segurança e acessibilidade tornam-se as primeiras coisas a se pensar. Você pode definitivamente otimizar o WordPress para ser bem rápido, mas mais rápido do que um site estático em um CDN que não precisa consultar o banco de dados nem gerar sua página toda vez? Não tão fácil.

Achei que poderia colocar isso em prática com um projeto pessoal meu para aprender e depois poder usar isso para projetos profissionais, e talvez alguns de vocês também gostariam de saber como. Neste artigo, falarei sobre como fiz a transição do WordPress para um gerador de site estático específico chamado Hugo.

Hugo é construído em Go, que é uma linguagem bem rápida e fácil de usar quando você se acostuma com a sintaxe, que vou explicar. Tudo é compilado localmente para que você possa visualizar seu site diretamente no seu computador. O projeto será então salvo em um repositório privado. Além disso, mostrarei como hospedá-lo no Netlify e salvar suas imagens em um Git LFS (Large File Storage). Por fim, veremos como podemos configurar um sistema de gerenciamento de conteúdo para adicionar postagens e imagens (semelhante ao backend do WordPress) com o Netlify CMS.

Observe que tudo isso é totalmente gratuito, o que é incrível se você me perguntar (embora você tenha que pagar mais se usar todo o armazenamento LFS ou se o tráfego do site for intenso). Além disso, estou escrevendo isso do ponto de vista do usuário do Bitbucket, rodando em um Mac. Algumas etapas podem ser um pouco diferentes, mas você deve conseguir acompanhar, independentemente da configuração usada.

Você precisará estar um pouco confortável com HTML, CSS, JS, Git e o terminal de comando. Ter algumas noções com linguagens de modelagem como Liquid também pode ser útil, mas revisaremos os modelos de Hugo para você começar. No entanto, vou fornecer o máximo de detalhes possível!

Eu sei que parece muito, e antes de começar a investigar isso, era para mim também. Vou tentar fazer essa transição o mais suave possível para você, dividindo as etapas. Não é muito difícil encontrar todos os recursos, mas houve um pouco de adivinhação da minha parte, indo de uma documentação para outra.

1. Exportando o conteúdo do WordPress
2. Preparando o design do seu blog
3. Configurando um novo repositório
4. Ativando o Git LFS (opcional)
5. Criando o site no Netlify
6. Preparação para mídia grande Netlify (opcional)
7. Configurando o Hugo em seu computador
8. Criando seu tema personalizado
9. Notas sobre a sintaxe de Hugo
10. Conteúdo e dados
11. Implantando no Netlify
12. Configurando um domínio personalizado
13. Editando conteúdo no Netlify CMS

Nota : Se você tiver problemas com alguns deles, por favor me avise nos comentários e tentarei ajudar, mas observe que isso é destinado a ser aplicado a um blog simples e estático que não possui uma dúzia de widgets ou comentários (você pode configurar isso mais tarde), e não um site da empresa ou portfólio pessoal. Você, sem dúvida, poderia, mas por uma questão de simplicidade, vou me ater a um blog simples e estático.

Pré-requisitos

Antes de fazermos qualquer coisa, vamos criar uma pasta de projeto onde tudo, desde nossas ferramentas até nosso repositório local, residirá. Vou chamá-lo de “WP2Hugo” (sinta-se à vontade para chamá-lo do que quiser).

Este tutorial fará uso de algumas ferramentas de linha de comando, como npm e Git. Se você ainda não os tiver, instale-os em sua máquina:

• Instalar o Git
• Instale o Node.js e o npm (o Node.js inclui o npm)
• Instale o Homebrew (recomendado para usuários de macOS/Linux)

Com eles instalados, vamos começar!

1. Exportando o conteúdo do WordPress

Primeiro, precisaremos exportar seu conteúdo do WordPress: postagens, páginas e uploads. Existem algumas ferramentas disponíveis que Hugo menciona, mas pessoalmente, apenas uma delas funcionou: blog2md. Este funciona executando um arquivo JavaScript com Node.js em seu terminal de comando. Ele pega os arquivos XML exportados pelo WordPress e gera arquivos Markdown com a estrutura correta, convertendo seu HTML em Markdown e adicionando o que é chamado de Front Matter, que é uma forma de formatar metadados no início de cada arquivo.

Vá para o seu administrador do WordPress e abra o menu Ferramentas, submenu Exportar. Você pode exportar o que quiser de lá. Vou me referir ao arquivo exportado como YOUR-WP-EXPORT.xml .

Você pode selecionar exatamente quais dados deseja exportar do seu blog WordPress.

Dentro da nossa pasta WP2Hugo, recomendo criar uma nova pasta chamada blog2md na qual você colocará os arquivos da ferramenta blog2md, bem como sua exportação XML do WordPress ( YOUR-WP-EXPORT.xml ). Além disso, crie uma nova pasta chamada out onde suas postagens do Markdown irão. Em seguida, abra seu terminal de comando e navegue com o comando cd para a pasta “blog2md” recém-criada (ou digite cd com um espaço e arraste a pasta para o terminal).

Agora você pode executar os seguintes comandos para obter suas postagens:

 npm install node index.js w YOUR-WP-EXPORT.xml out

Procure no /WP2Hugo/blog2md/out para verificar se todos os seus posts (e páginas potenciais) estão lá. Nesse caso, você pode notar que há algo sobre comentários na documentação: eu tinha um blog sem comentários, então não precisava que eles fossem executados, mas Hugo oferece várias opções para comentários. Se você tiver comentários no WordPress, poderá exportá-los para reimplementação posterior com um serviço especializado como o Disqus.

Se você estiver familiarizado o suficiente com JS, você pode ajustar o arquivo index.js para alterar como seus arquivos de postagem serão editados pela função wordpressImport . Você pode capturar a imagem em destaque, remover o link permanente, alterar o formato da data ou definir o tipo (se você tiver postagens e páginas). Você terá que adaptá-lo às suas necessidades, mas saiba que o loop ( posts.forEach(function(post){ ... }) ) percorre todos os posts da exportação, para que você possa verificar o conteúdo XML de cada post nesse loop e personalize seu Front Matter.

Além disso, se você precisar atualizar os URLs contidos em suas postagens (no meu caso, eu queria tornar os links das imagens relativos em vez de absolutos) ou a formatação da data, este é um bom momento para fazê-lo, mas não perca o sono por isso . Muitos editores de texto oferecem edição em massa para que você possa inserir uma expressão regular e fazer as alterações desejadas em seus arquivos. Além disso, você pode executar o script blog2md quantas vezes forem necessárias, pois ele substituirá qualquer arquivo existente anteriormente na pasta de saída.

Depois de ter seus arquivos Markdown exportados, seu conteúdo está pronto. O próximo passo é deixar seu tema WordPress pronto para funcionar no Hugo.

2. Preparando o design do seu blog

Meu blog tinha um layout típico com um cabeçalho, uma barra de navegação, conteúdo e barra lateral e um rodapé – bem simples de configurar. Em vez de copiar partes do meu tema WordPress, reconstruí tudo do zero para garantir que não houvesse estilos supérfluos ou marcações inúteis. Este é um bom momento para implementar novas técnicas de CSS ( pssst… Grid é incrível! ) e configurar uma estratégia de nomenclatura mais consistente (algo como as diretrizes do CSS Wizardry). Você pode fazer o que quiser, mas lembre-se de que estamos tentando otimizar nosso blog, então é bom revisar o que você tinha e decidir se ainda vale a pena mantê-lo.

Comece dividindo seu blog em partes para que você possa ver claramente o que vai para onde. Isso ajudará você a estruturar sua marcação e seus estilos. A propósito, Hugo tem a capacidade interna de compilar Sass para CSS, então sinta-se à vontade para dividir esses estilos em arquivos menores o quanto quiser!

Quando digo simples, quero dizer realmente simples.

Alternativamente, você pode ignorar completamente esta etapa por enquanto e estilizar seu blog à medida que seu site Hugo estiver configurado. Eu tinha a marcação básica em vigor e preferia uma abordagem iterativa aos estilos. Também é uma boa maneira de ver o que funciona e o que não funciona.

3. Configurando um novo repositório

Agora que isso está fora do caminho, precisamos configurar um repositório. Eu vou assumir que você vai querer criar um novo repositório para isso, que será uma ótima oportunidade para usar o Git LFS (Large File System). A razão pela qual eu aconselho fazer isso agora é que implementar o Git LFS quando você já tem centenas de imagens não é tão fácil. Eu fiz isso, mas foi uma dor de cabeça que você provavelmente vai querer evitar. Isso também fornecerá outros benefícios no futuro com o Netlify.

Embora eu esteja fazendo tudo isso via Bitbucket e sua GUI proprietária do Git, Sourcetree, você pode fazer isso com o GitHub e o GitLab e suas próprias ferramentas de desktop. Você também pode fazer isso diretamente no terminal de comando, mas eu gosto de automatizar e simplificar o processo ao máximo, reduzindo o risco de cometer erros bobos.

Quando você tiver criado seu novo repositório na plataforma Git de sua escolha, crie uma pasta vazia dentro da pasta do seu projeto local (WP2Hugo), por exemplo hugorepo , então abra seu terminal de comando ou ferramenta Git GUI e inicialize seu repositório Git local; em seguida, vincule-o ao repositório remoto (geralmente você pode encontrar o comando exato a ser usado no repositório remoto recém-criado).

Eu recomendo criar um branch dev (ou stage ) para que seu branch principal seja usado estritamente para implantações de produção. Ele também limitará a geração de novas compilações somente quando você concluir uma série potencial de alterações. A criação de uma ramificação pode ser feita localmente ou na página remota do seu repositório.

O GitHub facilita a criação de uma ramificação clicando no alternador de ramificação e digitando um novo nome. No GitLab, você precisa abrir o menu suspenso “Plus” para acessar a opção. O Bitbucket exige que você abra o menu “Mais” à esquerda para abrir o menu deslizante e clique em “Criar uma ramificação” na seção “Começar a trabalhar”.

4. Ativando o Git LFS (opcional)

O Git Large File System é um recurso do Git que permite salvar arquivos grandes de forma mais eficiente, como documentos do Photoshop, arquivos ZIP e, no nosso caso, imagens. Como as imagens podem precisar de controle de versão, mas não são exatamente código, faz sentido armazená-las de maneira diferente dos arquivos de texto comuns. A maneira como funciona é armazenando a imagem em um servidor remoto, e o arquivo em seu repositório será um arquivo de texto que contém um ponteiro para esse recurso remoto.

Infelizmente, não é uma opção que você apenas clica para ativar. Você deve configurar seu repositório para ativar o LFS e isso requer algum trabalho localmente. Com o Git instalado, você precisa instalar uma extensão Git-LFS:

 git lfs install

Se, como eu, esse comando não funcionou para você, tente a alternativa Homebrew (para macOS ou Linux):

 brew install git-lfs

Feito isso, você terá que especificar quais arquivos rastrear em seu repositório. Hospedarei todas as imagens que carreguei na pasta /upload do WordPress em uma pasta de nome idêntico na minha configuração do Hugo, exceto que essa pasta estará dentro de uma pasta /static (que será resolvida na raiz depois de compilada). Decida sobre sua estrutura de pastas e rastreie seus arquivos dentro:

 git lfs track "static/uploads/*"

Isso rastreará qualquer arquivo dentro da pasta /static/uploads . Você também pode usar o seguinte:

 git lfs track "*.jpg"

Isso rastreará todos e quaisquer arquivos JPG em seu repositório. Você pode misturar e combinar apenas para rastrear JPGs em uma determinada pasta, por exemplo.

Com isso, você pode enviar seus arquivos de configuração do LFS para seu repositório e enviá-los para seu repositório remoto. Na próxima vez que você confirmar localmente um arquivo que corresponda à configuração de rastreamento do LFS, ele será “convertido” em um recurso LFS. Se estiver trabalhando em um branch de desenvolvimento, mescle este commit em seu branch principal.

Vamos agora dar uma olhada no Netlify.

5. Criando o Site na Netlify

Neste ponto, seu repositório está configurado, então você pode ir em frente e criar uma conta no Netlify. Você pode até fazer login com sua conta GitHub, GitLab ou Bitbucket, se desejar. Uma vez no painel, clique no botão “Novo site do Git” no canto superior direito e crie seu novo site Netlify.

Nota : Você pode deixar todas as opções em seus valores padrão por enquanto.

Selecione seu provedor Git: isso abrirá uma janela pop-up para autenticá-lo. Quando isso for feito, a janela será fechada e você verá uma lista de repositórios naquele provedor Git ao qual você tem acesso. Selecione seu repositório recém-criado e continue. Você será solicitado a algumas coisas, a maioria das quais você pode simplesmente deixar por padrão, pois todas as opções são editáveis ​​posteriormente.

Por enquanto, nas configurações do site, clique em "Alterar nome do site" e nomeie seu site como quiser - eu vou com chris-smashing-hugo-blog . Agora poderemos acessar o site via chris-smashing-hugo-blog.netlify.com : uma linda página 404!

6. Preparação para mídia grande Netlify (opcional)

Se você configurou o Git LFS e planeja usar o Netlify, siga estas etapas. É um pouco mais complicado, mas definitivamente vale a pena: permitirá que você defina strings de consulta em URLs de imagem que serão transformadas automaticamente.

Digamos que você tenha um link para portrait.jpg que é uma imagem de 900×1600 pixels. Com Netlify Large Media, você pode chamar o arquivo portrait.jpg?nf_resize=fit&w=420 , que o dimensionará proporcionalmente. Se você definir w e h e definir nf_resize=smartcrop , ele será redimensionado cortando para focar no ponto de interesse da imagem (conforme determinado por um algoritmo sofisticado, também conhecido como magia do cérebro do robô! ). Acho que essa é uma ótima maneira de ter miniaturas como as que o WordPress gera, sem precisar de vários arquivos para uma imagem no meu repositório.

Se isso soa atraente para você, vamos configurá-lo!

A primeira etapa é instalar a interface de linha de comando (CLI) do Netlify via npm:

 npm install netlify-cli -g

Se funcionou, executar o comando netlify deve resultar em informações sobre a ferramenta.

Você precisará então certificar-se de que está em sua pasta de repositório local (que chamei de “hugorepo” anteriormente) e execute:

 netlify login

Autorize o token. Em seguida, teremos que instalar o plugin Netlify Large Media. Corre:

 netlify plugins:install netlify-lm-plugin netlify lm:install

Deve haver uma linha de comando mostrada no final da mensagem resultante que você deve copiar (que deve se parecer com /Users/YOURNAME/.netlify/helper/path.bash.inc no Mac) — execute-a. Observe que o Keychain pode solicitar a senha de administrador da sua máquina no macOS.

O próximo passo é vincular o Netlify:

 netlify link

Você pode fornecer o nome do seu site aqui (eu forneci o nome chris-smashing-hugo-blog que dei anteriormente). Com isso, você só precisa configurar o recurso Large Media executando o seguinte:

 netlify lm:setup

Confirme essas novas alterações em seu repositório local e envie-as por push para a ramificação de desenvolvimento remoto. Eu tive alguns erros com Sourcetree e Keychain ao longo das linhas de git "credential-netlify" is not a git command . Se for esse o seu caso, tente enviar manualmente com estes comandos:

 git add -A git commit -m "Set up Netlify Large media" git push

Se isso não funcionar, talvez seja necessário instalar o Netlify Credencial Helper. Veja como fazer isso com o Homebrew:

 brew tap netlify/git-credential-netlify brew install git-credential-netlify

Tente enviar seu commit agora (com sua GUI ou terminal de comando): deve funcionar!

Nota : Se você alterar sua senha do Netlify, execute netlify logout netlify e netlify login novamente.

Você pode perguntar: “Tudo isso, e ainda nem inicializamos nossa compilação do Hugo?” Sim, eu sei, demorou um pouco, mas todos os preparativos para a transição estão feitos. Agora podemos configurar nosso blog do Hugo!

7. Configurando o Hugo em seu computador

Você primeiro precisará instalar o Hugo em seu computador com qualquer uma das opções fornecidas. Estarei usando o Homebrew, mas os usuários do Windows podem usar o Scoop ou Chocolatey, ou baixar um pacote diretamente.

 brew install hugo

Você precisará criar um novo site Hugo, mas não vai gostar de configurá-lo em uma pasta não vazia. Primeira opção: você pode criá-lo em uma nova pasta e mover seu conteúdo para a pasta do repositório local:

 hugo new site your_temporary_folder

Segunda opção: você pode forçar a instalação em seu repositório local com um sinalizador, apenas certifique-se de estar executando isso na pasta correta:

 hugo new site . --force

Agora você tem um site Hugo, que você pode ativar com este comando:

 hugo server

Você obterá uma visualização local em localhost . Infelizmente, você não tem conteúdo nem tema próprio. Não se preocupe, vamos configurar isso muito em breve!

Vamos primeiro dar uma olhada no arquivo de configuração ( config.toml no meu caso): vamos configurar o nome do blog e a URL base (isso deve corresponder à URL no seu painel Netlify):

 title = "Chris' Smashing Hugo Blog" baseURL = "https://chris-smashing-hugo-blog.netlify.com"

Esse link será substituído enquanto você desenvolve localmente, portanto, você não deve encontrar erros 404.

Vamos dar ao Hugo nossos artigos exportados no formato Markdown. Eles devem estar na /WP2Hugo/blog2md/out desde o primeiro passo. Na pasta Hugo (também conhecida como diretório do repositório local), acesse a pasta content e crie uma subpasta chamada posts . Coloque seus arquivos Markdown lá e, em seguida, vamos configurar um tema.

8. Criando seu tema personalizado

Para esta etapa, recomendo baixar o clichê Saito, que é um tema com todos os parciais que você precisa para começar (e sem estilos) — um ponto de partida muito útil. Você pode, é claro, olhar para esta coleção de temas prontos para Hugo se quiser pular essa parte do processo. Está tudo nas tuas mãos!

Na pasta do repositório local, clone o tema em themes/saito :

 git submodule add https://github.com/hakuoku/saito-boilerplate.git themes/saito

Você pode renomear esta pasta para o que quiser, como cool-theme . Você terá que informar à sua configuração do Hugo qual tema deseja usar editando seu arquivo config.toml/yaml/json . Edite o valor do tema para saito , ou cool-theme , ou qualquer que seja o nome da pasta do seu tema. Sua visualização agora deve mostrar o título do seu blog junto com uma linha de direitos autorais. É um começo, certo?

Abra o arquivo layout/partials/home.html do tema e edite-o para exibir seu conteúdo, limitando aos cinco primeiros itens que são do tipo posts (dentro da pasta content/posts/ ), com range , first e where :

 <div class="container"> {{ range first 5 (where .Paginator.Pages "Type" "posts") }} <article class="post post--{{ .Params.class }}"> <h2 class="post__title">{{ .Title }}</h2> <section class="post__content"> {{ .Content }} </section> </article> {{ end }} </div>

Seu conteúdo agora está visível, da maneira mais básica. É hora de torná-lo seu - vamos mergulhar!

Modelando com Hugo

Você pode primeiro ler a introdução ao modelo de Hugo, se quiser, mas tentarei passar por cima de alguns fundamentos que ajudarão você a entender o básico.

Todas as operações no Hugo são definidas dentro de delimitadores: chaves duplas (por exemplo, {{ .Title }} ), que deve parecer familiar se você já fez um pouco de modelagem antes. Se você não tiver, pense nisso como uma maneira de executar operações ou injetar valores em um ponto específico em sua marcação. Para blocos, eles terminam com a tag {{ end }} , para todas as operações, exceto códigos de acesso.

Os temas têm uma pasta de layout que contém as partes do layout. A pasta _default será o ponto de partida do Hugo, sendo baseof.html ( você adivinhou! ) a base do seu layout. Ele chamará cada componente, chamado de “partials” (mais sobre isso na documentação do Hugo sobre Partial Template), semelhante a como você usaria include no PHP, que você já deve ter visto no seu tema WordPress. Partials podem chamar outros parciais - apenas não faça disso um loop infinito.

Você pode chamar um parcial com {{ partial "file.html" . }} {{ partial "file.html" . }} sintaxe. A seção partial é bastante direta, mas as outras duas podem precisar de explicação. Você pode esperar ter que escrever parciais/arquivo.html , mas como todos os parciais devem estar na pasta parciais”, Hugo pode encontrar essa pasta bem. Claro, você pode criar subpastas dentro da pasta “partials” se precisar de mais organização.

Você deve ter notado um ponto perdido: este é o contexto que você está passando para sua parcial. Se você tivesse um menu parcial e uma lista de links e rótulos, você poderia passar essa lista para o parcial para que ele pudesse acessar apenas essa lista e nada mais. Falarei mais sobre esse ponto indescritível na próxima seção.

Seu arquivo baseof.html é um shell que chama todos os vários parciais necessários para renderizar o layout do seu blog. Deve ter HTML mínimo e muitos parciais:

 <!DOCTYPE html> <html lang="{{ .Site.LanguageCode }}"> <head> <title>{{ block "title" . }}{{ .Site.Title }}{{ end }}</title> {{ partial "head.html" . }} </head> <body> {{ partial "header.html" . }} {{ partial "nav.html" . }} <main> {{ block "main" . }}{{ end }} </main> <aside> {{ partial "sidebar.html" . }} </aside> {{ partial "footer.html" . }} </body> </html>

O {{ block "main" . }}{{ end }} A linha {{ block "main" . }}{{ end }} é diferente porque é um bloco que é definido com um template baseado no conteúdo da página atual (homepage, single post page, etc.) com {{ define "main" }} .

Folhas de estilo

Em seu tema, crie uma pasta chamada assets na qual colocaremos uma pasta css . Ele conterá nossos arquivos SCSS, ou um arquivo CSS antigo e confiável. Agora, deve haver um arquivo css.html na pasta partials (que é chamada por head.html ). Para converter Sass/SCSS para CSS e minimizar a folha de estilo, usaríamos esta série de funções (usando a sintaxe do Hugo Pipes em vez de agrupar as funções umas nas outras):

 {{ $style := resources.Get "css/style.scss" | toCSS | minify | fingerprint }}

Como um bônus - já que me esforcei para encontrar uma resposta direta - se você quiser usar o Autoprefixer, o Hugo também implementa o PostCSS. Você pode adicionar uma função pipe extra entre toCSS e minify na primeira linha, assim:

 {{ $style := resources.Get "css/style.scss" | toCSS | postCSS | minify | fingerprint }}

Crie um arquivo “postcss.config.js” na raiz do seu blog Hugo e passe as opções, como:

 module.exports = { plugins: { autoprefixer: { browsers: [ "> 1%", "last 2 versions" ] } }, }

E pronto! De Sass a CSS reduzido e prefixado. A função de pipe “fingerprint” é garantir que o nome do arquivo seja único, como style.c66e6096bdc14c2d3a737cff95b85ad89c99b9d1.min.css . Se você alterar a folha de estilo, a impressão digital será alterada, portanto, o nome do arquivo será diferente e, portanto, você obterá uma solução eficaz de bloqueio de cache.

9. Notas sobre a sintaxe de Hugo

Quero ter certeza de que você entendeu “the Dot”, que é como Hugo define os escopos das variáveis ​​(ou, em minhas próprias palavras, fornece uma referência contextual) que você usará em seus templates.

O ponto e o escopo

O Dot é como uma variável de nível superior que você pode usar em qualquer modelo ou código de acesso, mas seu valor está no escopo de seu contexto. O valor do Dot em um modelo de nível superior como baseof.html é diferente do valor dentro de blocos de loop ou with blocos.

Digamos que isso esteja em nosso modelo em nossa parcial head.html :

 {{ with .Site.Title }} {{ fim }}

Embora estejamos executando isso no escopo principal, o valor do Dot muda com base no contexto, que é .Site.Title neste caso. Então, para imprimir o valor, você só precisa escrever . em vez de digitar novamente o nome da variável. Isso me confundiu no começo, mas você se acostuma muito rápido e ajuda a reduzir a redundância, pois você só nomeia a variável uma vez. Se algo não funcionar, geralmente é porque você está tentando chamar uma variável de nível superior dentro de um bloco com escopo definido.

Então, como você usa o escopo de nível superior dentro de um bloco com escopo definido? Bem, digamos que você queira verificar um valor, mas use outro. Você pode usar $ que sempre será o escopo de nível superior:

 {{ with .Site.Params.InfoEnglish }}{{ $.Site.Params.DescriptionEnglish }}{{ end }}

Dentro de nossa condição, o escopo é .Site.Params.InfoEnglish mas ainda podemos acessar valores fora dele com $ , onde intuitivamente usar .Site.Params.DescriptionEnglish não funcionaria porque tentaria resolver para .Site.Params.InfoEnglish.Site.Params.DescriptionEnglish , lançando um erro.

Variáveis ​​personalizadas

Você pode atribuir variáveis ​​usando a seguinte sintaxe:

 {{ $customvar := "custom value" }}

O nome da variável deve começar com $ e o operador de atribuição deve ser := se for a primeira vez que está sendo atribuído, = caso contrário, assim:

 {{ $customvar = "updated value" }}

O problema que você pode encontrar é que isso não sairá do escopo, o que me leva ao próximo ponto.

Arranhar

A funcionalidade Scratch permite atribuir valores que estão disponíveis em todos os contextos. Digamos que você tenha uma lista de filmes em um arquivo movies.json :

 [ { "name": "The Room", "rating": 4 }, { "name": "Back to the Future", "rating": 10 }, { "name": "The Artist", "rating": 7 } ]

Agora, você deseja iterar sobre o conteúdo do arquivo e armazenar o seu favorito para usar mais tarde. É aqui que o Scratch entra em ação:

 {{ .Scratch.Set "favouriteMovie" "None" }}{{ /* Optional, just to get you to see the difference syntax based on the scope */ }} {{ range .Site.Data.movies }} {{ if ge .rating 10 }} {{ /* We must use .Scratch prefixed with a $, because the scope is .Site.Data.movies, at the current index of the loop */ }} {{ $.Scratch.Set "favouriteMovie" .name }} {{ end }} {{ end }} [...] My favourite movie is {{ .Scratch.Get "favouriteMovie" }} <!-- Expected output => My favourite movie is Back to the Future -->

Com o Scratch, podemos extrair um valor de dentro do loop e usá-lo em qualquer lugar. À medida que seu tema se torna cada vez mais complexo, você provavelmente se encontrará no Scratch.

Nota : Este é apenas um exemplo, pois esse loop pode ser otimizado para gerar esse resultado sem o Scratch, mas isso deve fornecer uma melhor compreensão de como ele funciona.

Condicionais

A sintaxe para condicionais é um pouco diferente do que você esperaria — de uma perspectiva JavaScript ou PHP. Existem, em essência, funções que recebem dois argumentos (parênteses opcionais se você chamar os valores diretamente):

 {{ if eq .Site.LanguageCode "en-us" }}Welcome!{{ end }}

Existem várias dessas funções:

• eq verifica a igualdade
• ne verifica a desigualdade
• gt verifique para maior que
• ge cheque para grande ou igual a
• lt verifica menor que
• le verifica para menor ou igual a

Nota : Você pode aprender tudo sobre as funções que o Hugo oferece no Hugo Functions Quick Reference.

Espaço em branco

Se você for tão exigente quanto eu com a saída, poderá notar algumas linhas em branco indesejadas. Isso ocorre porque o Hugo analisará sua marcação como está, deixando linhas em branco em torno de condicionais que não foram atendidas, por exemplo.

Digamos que temos essa parcial hipotética:

 {{ if eq .Site.LanguageCode "en-us" }} <p>Welcome to my blog!</p> {{ end }} <img src="/uploads/portrait.jpg" alt="Blog Author">

Se o código de idioma do site não for en-us , esta será a saída HTML (observe as três linhas vazias antes da tag de imagem):

 <img src="/uploads/portrait.jpg" alt="Blog Author">

Hugo fornece uma sintaxe para resolver isso com um hífen ao lado das chaves na parte interna do delimitador. {{- cortará o espaço em branco antes das chaves e -}} cortará o espaço em branco após as chaves. Você pode usar um ou ambos ao mesmo tempo, mas apenas certifique-se de que haja um espaço entre o hífen e a operação dentro do delimitador.

Como tal, se o seu modelo contiver o seguinte:

 {{- if eq .Site.LanguageCode "en-us" -}} <p>Welcome to my blog!</p> {{- end -}} <img src="/uploads/portrait.jpg" alt="Blog Author">

…então a marcação resultará nisso (sem linhas vazias):

 <img src="/uploads/portrait.jpg" alt="Blog Author">

Isso pode ser útil para outras situações como elementos com display: inline-block que não deve ter espaços em branco entre eles. Por outro lado, se você quiser ter certeza de que cada elemento está em sua própria linha na marcação (por exemplo, em um loop {{ range }} ), você terá que colocar seus hífens com cuidado para evitar cortes “gananciosos” de espaços em branco.

O exemplo acima produziria o seguinte se o código de idioma do site corresponder a “ en-us ” (sem mais quebras de linha entre as tags p e img ):

 <p>Welcome to my blog!</p><img src="/uploads/portrait.jpg" alt="Blog Author">

10. Conteúdo e dados

Seu conteúdo é armazenado como arquivos Markdown, mas você também pode usar HTML. Hugo irá renderizá-lo corretamente ao construir seu site.

Sua página inicial chamará o layout _default/list.html , que pode ter esta aparência:

 {{ define "main" }} {{ partial "list.html" . }} {{ end }}

O bloco principal chama o list.html parcial com o contexto de . , também conhecido como o nível superior. A parcial list.html pode ter esta aparência:

 {{ define "main" }} <ol class="articles"> {{ range .Paginator.Pages }} <li> <article> <a href="{{ .URL }}"> <h2>{{ .Title }}</h2> <img src="{{ .Params.featuredimage }}" alt=""> <time datetime="{{ .Date.Format "2006-01-02" }}"> {{ .Date.Format "January 2 2006" }} </time> </a> </article> </li> {{ end }} </ol> {{ partial "pagination.html" . }} {{ end }}

Agora temos uma lista básica de nossos artigos, que você pode estilizar como quiser! O número de artigos por página é definido no arquivo de configuração, com paginate = 5 (em TOML).

Você pode estar totalmente confuso como eu estava pela formatação de data em Hugo. Cada vez que a unidade é mapeada para um número (primeiro mês, segundo dia, terceira hora, etc.) mas meio inteligente também!

 Jan 2 15:04:05 2006 MST => 1 2 3 4 5 6 -7

Agora tudo o que resta a fazer é exibir sua postagem em uma única página. Você pode editar o post.html parcial para personalizar o layout do seu artigo:

 <article> <header> <h1>{{ .Title }}</h1> <p> Posted on <time datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "2006. 1. 2" }}</time> </p> </header> <section> {{ .Content }} </section> </article>

E é assim que você exibe seu conteúdo!

Se você quiser personalizar a URL, atualize seu arquivo de configuração adicionando uma opção [permalinks] (TOML), que neste caso fará com que as URLs pareçam my-blog.com/post-slug/ :

 [permalinks] posts = ":filename/"

Se você deseja gerar um feed RSS do seu conteúdo (porque o RSS é incrível), adicione o seguinte no arquivo de configuração do site (o modelo padrão do Saito exibirá as tags apropriadas em head.html se essas opções forem detectadas):

 rssLimit = 10 [outputFormats] [outputFormats.RSS] mediatype = "application/rss" baseName = "feed"

Mas e se você tivesse algum tipo de conteúdo fora de uma postagem? É aí que entram os templates de dados: você pode criar arquivos JSON e extrair seus dados para criar seu menu ou um elemento em sua barra lateral. YAML e TOML também são opções, mas menos legíveis com dados complexos (por exemplo, objetos aninhados). Você pode, é claro, definir isso no arquivo de configuração do seu site, mas é – para mim – um pouco menos fácil de navegar e menos tolerante.

Vamos criar uma lista de “sites legais” que você pode querer mostrar em sua barra lateral — com um link e um rótulo para cada site como um array em JSON:

 { "coolsites": [ { "link": "https://smashingmagazine.com", "label": "Smashing Magazine" }, { "link": "https://gohugo.io/", "label": "Hugo" }, { "link": "https://netlify.com", "label": "Netlify" } ] }

Você pode salvar esse arquivo na raiz do repositório ou na raiz do tema, dentro de uma pasta de data , como /data/coolsites.json . Então, na sua parcial sidebar.html , você pode iterar sobre ela com range usando .Site.Data.coolsites :

 <h3>Cool Sites:</h3> <ul> {{ range .Site.Data.coolsites.coolsites }} <li><a href="{{ .link }}">{{ .label }}</a></li> {{ end }} </ul>

Isso é muito útil para qualquer tipo de dado personalizado que você deseja iterar. Usei-o para criar uma lista do Google Fonts para o meu tema, em quais categorias os posts podem estar, autores (com bio, avatar e link da página inicial), quais menus mostrar e em que ordem. Você pode realmente fazer muito com isso, e é bastante simples.

Um pensamento final sobre dados e tal: qualquer coisa que você colocar em sua pasta Hugo /static estará disponível na raiz ( / ) na compilação ao vivo. O mesmo vale para a pasta do tema.

11. Implantação no Netlify

Então você está pronto, ou talvez você só queira ver que tipo de mágica o Netlify opera? Parece bom para mim, desde que seu servidor Hugo local não retorne um erro.

Confirme suas alterações e envie-as para seu branch de desenvolvimento remoto ( dev ). Vá para o Netlify em seguida e acesse as configurações do seu site. Você verá uma opção para “Build & deploy”. Vamos precisar mudar algumas coisas aqui.

1. Primeiro, na seção “Configurações de compilação”, certifique-se de que “Comando de compilação” esteja definido como hugo e que “Diretório de publicação” esteja definido como public (o padrão recomendado que você mantenha no arquivo de configuração do Hugo);
2. Em seguida, na seção “Deploy contexts”, defina “Production branch” para seu branch principal em seu repositório. Também sugiro que seu “branch deploys” seja definido como “Deploy only the production branch”;
3. Por fim, na seção “Variáveis ​​de ambiente”, edite as variáveis ​​e clique em “Nova variável”. Vamos definir o ambiente Hugo para 0,53 com o seguinte par: set key para HUGO_VERSION e value para 0.53 .

Agora vá para o seu repositório remoto e mescle sua ramificação de desenvolvimento em sua ramificação principal: este será o gancho que implantará seu blog atualizado (isso pode ser personalizado, mas o padrão é razoável para mim).

De volta ao seu painel Netlify, as “implantações de produção” do seu site devem ter alguma nova atividade. Se tudo deu certo, isso deve ser processado e resolvido para um rótulo "Publicado". Clicar no item de implantação abrirá uma visão geral com um log das operações. No topo, você verá “Preview deploy”. Vá em frente, clique nele - você merece. Está vivo!

12. Configurando um domínio personalizado

Ter a URL como my-super-site.netlify.com não é do seu agrado, e você já possui my-super-site.com ? Entendi. Vamos mudar isso!

Vá até o registrador de seu domínio e vá para as configurações de DNS do seu domínio. Aqui, você terá que criar uma nova entrada: você pode definir um registro ALIAS/CNAME que aponta para my-super-site.netlify.com ou definir um registro A que aponta seu domínio para o balanceador de carga da Netlify, que é 104.198.14.52 no momento da redação.

Você pode encontrar as informações mais recentes na documentação da Netlify sobre domínios personalizados. O IP do balanceador de carga estará na seção de configurações de DNS, em “Configuração de DNS manual para domínios personalizados raiz e www”.

Quando terminar, vá até o painel do seu site no Netlify e clique em “Configurações de domínio”, onde você verá “Adicionar domínio personalizado”. Digite seu nome de domínio para verificá-lo.

Você também pode gerenciar seus domínios por meio de seu painel na guia Domínios. A interface parece menos confusa nesta página, mas talvez ajude a entender melhor suas configurações de DNS, como aconteceu comigo.

Nota : Netlify também pode lidar com tudo para você se você quiser comprar um domínio através deles. É mais fácil, mas é um custo extra.

Depois de configurar seu domínio personalizado, em "Configurações do domínio", role para baixo até a seção "HTTPS" e ative o certificado SSL/TLS. Pode demorar alguns minutos, mas concederá um certificado gratuito: seu domínio agora é executado em HTTPS.

13. Editando conteúdo no Netlify CMS

Se você quiser editar seus artigos, fazer upload de imagens e alterar as configurações do seu blog como faria na interface de back-end do WordPress, você pode usar o Netlify CMS, que tem um bom tutorial disponível. É um único arquivo que cuidará de tudo para você (e é independente de gerador: funcionará com Jekyll, Eleventy e assim por diante).

Você só precisa fazer upload de dois arquivos em uma pasta:

• o CMS (um único arquivo HTML);
• um arquivo de configuração (um arquivo YAML).

Este último manterá todas as configurações do seu site específico.

Vá para a pasta /static da sua raiz do Hugo e crie uma nova pasta que você acessará via my-super-site.com/FOLDER_NAME (vou chamar o meu admin ). Dentro desta pasta admin , crie um arquivo index.html copiando a marcação fornecida pelo Netlify CMS:

 <!doctype html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <!-- Include the script that builds the page and powers Netlify CMS --> <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script> </body> </html>

O outro arquivo que você precisará criar é o arquivo de configuração: config.yml . Ele permitirá que você defina as configurações do seu site (nome, URL, etc.) É um pouco mais complexo de configurar, mas isso não significa que não seja fácil.

Se você estiver usando o GitHub ou GitLab, inicie seu arquivo config.yml com:

 backend: name: git-gateway branch: dev # Branch to update (optional; defaults to master)

Se você estiver usando o Bitbucket, é um pouco diferente:

 backend: name: bitbucket repo: your-username/your-hugorepo branch: dev # Branch to update (optional; defaults to master)

Então, para nossos uploads, teremos que informar ao CMS onde armazená-los:

 media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads public_folder: "/images/uploads" # The src attribute for uploaded media will begin with /images/uploads

Quando você cria uma nova postagem, o CMS gera o slug para o nome do arquivo que você pode personalizar com três opções:

slug: encoding: "ascii" # You can also use "unicode" for non-Latin clean_accents: true # Removes diacritics from characters like e or a sanitize_replacement: "-" # Replace unsafe characters with this string

Por fim, você precisará definir como os dados em suas postagens são estruturados. Também definirei como o arquivo de dados coolsites está estruturado — caso eu queira adicionar outro site à lista. Eles são definidos com o objeto de collections que definitivamente será o mais detalhado, juntamente com um bom punhado de opções sobre as quais você pode ler mais aqui.

 collections: - name: "articles" # Used in routes, eg, /admin/collections/blog label: "Articles" # Used in the Netlify CMS user interface folder: "content/posts" # The path to the folder where the posts are stored, usually content/posts for Hugo create: true # Allow users to create new documents in this collection slug: "{{slug}}" # Filename template, eg, post-title.md fields: # The fields for each document, usually in front matter - {label: "Title", name: "title", widget: "string", required: true} - {label: "Draft", name: "draft", widget: "boolean", default: true } - {label: "Type", name: "type", widget: "hidden", default: "post" } - {label: "Publish Date", name: "date", widget: "date", format: "YYYY-MM-DD"} - {label: "Featured Image", name: "featuredimage", widget: "image"} - {label: "Author", name: "author", widget: "string"} - {label: "Body", name: "body", widget: "markdown"} - name: 'coolsites' label: 'Cool Sites' file: 'data/coolsites.json' description: 'Website to check out' fields: - name: coolsites label: Sites label_singular: 'Site' widget: list fields: - { label: 'Site URL', name: 'link', widget: 'string', hint: 'https://…' } - { label: 'Site Name', name: 'label', widget: 'string' }

Nota : Você pode ler mais sobre como configurar campos individuais na documentação Netlify CMS Widgets que aborda cada tipo de widget e como usá-los — especialmente útil para formatos de data.

Autenticação

A última coisa que precisamos fazer é garantir que apenas usuários autorizados possam acessar o back-end! Usar a autenticação do seu provedor Git é uma maneira fácil de fazer isso.

Vá até o seu site Netlify e clique na guia “Configurações”. Em seguida, vá para “Controle de acesso”, que é o último link do menu do lado esquerdo. Aqui, você pode configurar o OAuth para ser executado via GitHub, GitLab ou Bitbucket fornecendo uma chave e um valor secreto definido para sua conta de usuário (não no repositório). Você desejará usar o mesmo provedor Git em que seu repositório está salvo.

GitHubGenericName

Vá para a página “Configurações” no GitHub (clique no seu avatar para revelar o menu) e acesse “Configurações do desenvolvedor”. Clique em “Registrar um novo aplicativo” e forneça os valores necessários:

• um nome, como “Netlify CMS para meu superblog”;
• um URL da página inicial, o link para seu site Netlify;
• uma descrição, se quiser;
• o URL de retorno de chamada do aplicativo, que deve ser “ https://api.netlify.com/auth/done ”.

Salve e você verá seu ID do cliente e Segredo do cliente. Forneça-os ao Controle de Acesso da Netlify.

GitLabGenericName

Clique no seu avatar para acessar a página Configurações e clique em “Aplicativos” no menu “Configurações do usuário” à esquerda. Você verá um formulário para adicionar um novo aplicativo. Providencie a seguinte informação:

• um nome, como “Netlify CMS para meu superblog”;
• um URI de redirecionamento, que deve ser “ https://api.netlify.com/auth/done ”;
• os escopos que devem ser verificados são:
  • api
  • read_user
  • read_repository
  • write_repository
  • read_registry

Salvar seu aplicativo lhe dará seu ID e Segredo do Aplicativo, que agora você pode inserir no Controle de Acesso da Netlify.

Bitbucket

Vá para as configurações da sua conta de usuário (clique no seu avatar e depois em “Configurações do Bitbucket”). Em “Gerenciamento de acesso”, clique em “OAth”. Na seção "Consumidores OAuth", clique em "Adicionar consumidor". Você pode deixar a maioria das coisas em seus valores padrão, exceto por estes:

• um nome, como “Netlify CMS para meu superblog”;
• um URL de retorno de chamada, que deve ser “ https://api.netlify.com/auth/done ”;
• as permissões que devem ser verificadas são:
  • Conta: E-mail, Ler, Escrever
  • Repositórios: Ler, Escrever, Admin
  • Pull Requests: Ler, Escrever
  • Webhooks: ler e escrever

Depois de salvar, você pode acessar sua chave e segredo, que você pode fornecer de volta no Controle de Acesso da Netlify.

Depois de fornecer os tokens, vá para Netlify e encontre as configurações do site. Vá para “Identidade” e ative o recurso. Agora você pode adicionar um provedor externo: selecione seu provedor Git e clique em “Ativar”.

Caso você precise de detalhes adicionais, o Netlify CMS tem um guia de autenticação que você pode ler.

Agora você pode acessar o backend do seu site Netlify e editar o conteúdo. Cada edição é um commit em seu repositório, na ramificação especificada em seu arquivo de configuração. Se você manteve seu branch main como destino do Netlify CMS, cada vez que você salvar, ele executará uma nova compilação. Mais conveniente, mas não tão limpo com “estados intermediários”.

Salvar em uma ramificação dev permite que você tenha um controle mais preciso sobre quando deseja executar uma nova compilação. Isso é especialmente importante se o seu blog tiver muito conteúdo e exigir um tempo de construção mais longo. De qualquer maneira funcionará; é apenas uma questão de como você deseja executar seu blog .

Além disso, observe que o Git LFS é algo que você instalou localmente, portanto, as imagens enviadas via Netlify CMS serão “normais”. Se você fizer pull em sua ramificação remota localmente, as imagens devem ser convertidas em LFS, que você pode confirmar e enviar para sua ramificação remota. Além disso, o Netlify CMS atualmente não suporta LFS, então a imagem não será exibida no CMS, mas aparecerá na sua versão final.

Leitura recomendada : Geradores de sites estáticos revisados: Jekyll, Middleman, Roots, Hugo

Conclusão

Que viagem! Neste tutorial, você aprendeu como exportar seu post WordPress para arquivos Markdown, criar um novo repositório, configurar o Git LFS, hospedar um site no Netlify, gerar um site Hugo, criar seu próprio tema e editar o conteúdo com o Netlify CMS . Não é tão ruim!

Qual é o próximo? Bem, você pode experimentar com sua configuração do Hugo e ler mais sobre as várias ferramentas que o Hugo oferece - há muitas que eu não abordei por uma questão de brevidade.

Explorar! Divirta-se! Blogue!

Recursos adicionais

• Documentação Hugo
  • Instalação
  • Começo rápido
  • Configuração
  • Modelagem
  • Taxonomias
  • Códigos de acesso
  • Hugo na Netlify
• Documentação Netlify
  • Domínios personalizados
  • DNS gerenciado
  • Scripts de implantação netlify.toml
• Documentação do Netlify CMS
  • Widgets
• Git LFS