Criar um site com Hugo Framework é extremamente rápido e fácil, mas um site fica melhor ainda e mais funcional quando inclui um gerenciador de conteúdo (CMS), e é justamente isso que iremos fazer nesse tutorial.
Faremos a integração do TinaCMS a um site feito em Hugo Framework que está hospedado no Netlify.
TinaCMS é uma ótima opção, pois já traz diversos recursos prontos para uso como toda uma client para editar suas páginas e autenticação na nuvem via Tina Cloud para ser usado em produção.
Pré-requisitos:
-
NodeJS
Caso não tenha instalado, segue o link para baixar e instalar
-
Site em Hugo no Github e hospedado no Netlify
Caso não tenha um site, nesse tutorial ensino como criar
https://tiagoscosta.com.br/posts/hugo-criando-o-primeiro-site/
Nesse ensino como enviar para o Github e como hospedar no Netlify
https://tiagoscosta.com.br/posts/hugo-hospedando-site-no-netlify/
Recomendo estar hospedado no Netlify, pois na parte de disponibilizar em produção, faço todas as configurações no Netlify
-
Conta no Tina Cloud (É gratuito)
No meu caso estou fazendo login com o Github
Link do serviço para criar sua conta
Configurando o TinaCMS no modo local Link para o cabeçalho
Melhor opção para trabalhar localmente ou em desenvolvimento.
No terminal, no meu caso no PowerShell do Windows, na raiz do seu projeto, instale o TinaCMS.
# No meu caso faço uso do fnm para versionar o NodeJs, então preciso roda
# Talvez na sua máquina não precise desse comando
fnm env --use-on-cd | Out-String | Invoke-Expression
fnm use default # (seleciono a versão que irei usar)
# Instala o TinaCMS
npx @tinacms/cli@latest init
# Será feito algumas perguntas, selecione de acordo com as instruções abaixo:
# √ What framework are you using? » Hugo
# √ Choose your package manager » NPM
# ? Would you like to use Typescript for your Tina Configuration (Recommended)? » Y
Se ocorreu tudo bem com a instalação do TinaCMS, no terminal, você pode subir localmente o CMS junto com o seu site com o comando
# Sobe TinaCMS junto com o site Hugo
npx tinacms dev -c "hugo server -D"
Agora acesse a parte admin do TinaCMS, através do link
http://localhost:1313/admin
Você verá que o TinaCMS informa que você está no modo local e já mostra uma postagem chamada Hello, World!, que foi uma criação de exemplo do próprio TinaCMS durante a instalação.
TinaCMS faz uso de Markdown para criar as postagens, se você tiver alguma postagem anterior em algum outro formato, será necessário fazer a conversão para Markdown.
Exemplo: No site já tinha uma postagem chamada My first post no formato Rich Text, dessa forma:
+++
title = 'My First Post'
date = 2024-11-17T18:34:57-03:00
draft = false
+++
Conteúdo
Tive que converter para Markdown, então a postagem ficou da seguinte forma:
---
title: My First Post
date: 2024-11-17T18:34:57-03:00
draft: false
---
Conteúdo
Se você voltar lá na tela do TinaCMS e der um refresh, verá que agora ele mostrará a postagem anterior, pois agora foi convertida para Markdown.
A partir de agora você já pode editar suas postagens localmente através desse ótimo CMS.
Caso queira encerrar o serviço, é só voltar no terminar e pressionar as teclas CTRL + C.
Configurando o TinaCMS no modo produção Link para o cabeçalho
Começaremos pelo Tina Cloud para que possamos começar a nossa configuração.
Antes de prosseguir, caso esteja rodando o TinaCMS local, cancele com as teclas CTRL + C.
Tina cloud configurando projeto Link para o cabeçalho
No Tina Cloud, clique no link Create Project
Na próxima tela clique em Import your Site
Agora clique em Authenticate With Github
Na janela que se abre, selecione Only select repositories, pesquise o repositório onde está seu site, selecione-o e depois clique em Install
Assim o Tina Cloud vai poder ter acesso ao repositório do seu site, para que possa ler e escrever postagens diretamente nele.
Agora na próxima tela, clique em Select, para selecionar o repositório.
Na próxima tela, clique em Create Project
Na tela que surge, veja que já tem um campo informando um Client ID, copie esse código e já reserve pois iremos utilizar em breve.
Depois clique no menu Tokens, copie os 2 tokens, copie o token Content (Readonly) e o token Search, e depois reserve separando bem cada um, pois iremos utilizar.
Configurando o site
Na pasta raiz do seu site crie um arquivo .env
É nele que adicionaremos as configurações para produção.
Adicione o conteúdo e salve.
Não esqueça de substituir a chave e tokens pelas que você obteve anteriormente
# Branch que o Tina Cloud irá manipular no Github
GITHUB_BRANCH=main
# Pegue no Tina Cloud, no seu projeto em "Overview"
TINA_CLIENT_ID=06ac9d80-e2c5-4c39-86f3-33b65ac45ccf
# Pegue no Tina Cloud, no seu projeto em "Token > Content (Readonly)"
TINA_TOKEN=6abdb45d8b624e1cdf42054bb1238638313e02ba
# Pegue no Tina Cloud, no seu projeto em "Token > search"
TINA_TOKEN_SEARCH=aa15f112adf203e0df91cd7dc188ca0c37159976
Agora iremos referenciar as informações no arquivo config.ts que está presente na pasta raiz tina do seu site.
No arquivo config.ts, na parte defineConfig, deixe da seguinte forma e salve:
export default defineConfig({
branch: process.env.GITHUB_BRANCH || "", // Branch github que será manibulada
// Get this from tina.io
clientId: process.env.TINA_CLIENT_ID || "", // Pegue no Tina Cloud, no seu projeto em "Overview"
// Get this from tina.io
token: process.env.TINA_TOKEN || "", // Pegue no Tina Cloud, no seu projeto em "Token > Content (Readonly)"
build: {
outputFolder: "admin",
publicFolder: "static",
},
media: {
tina: {
mediaRoot: "",
publicFolder: "static",
},
},
// See docs on content modeling for more info on how to setup new content models: https://tina.io/docs/schema/
schema: {
collections: [
{
name: "post",
label: "Postagens",
path: "content/posts",
fields: [
{
type: "string",
name: "title",
label: "Título",
isTitle: true,
required: true,
},
{
type: 'boolean',
name: 'draft',
label: 'É rascunho'
},
{
type: "rich-text",
name: "body",
label: "Conteúdo",
isBody: true,
},
],
},
],
},
search: { // Configuração de campo de busca
tina: {
indexerToken: process.env.TINA_TOKEN_SEARCH, // Pegue no Tina Cloud, no seu projeto em "Token > search"
stopwordLanguages: ['eng'],
},
indexBatchSize: 100,
maxSearchIndexFieldLength: 100,
},
});
Na linha 2 à 7, fiz o importe da branch, client id e token Content Readonly.
Na linha 27 à 44, personalizei os campos front matter (campos de metadados), adicionando mais campos e realizando a tradução deles.
Na linha 49 à 56, habilitei e configurei a busca no TinaCMS, pois por padrão, ela não vem habilitada.
No seu terminal, na raiz do site, comite essas alterações e envie para a branch, pois é ela que será manipulada pelo Tina Cloud.
# Adiciona alterações no git
git add .
# Comita alterações
git commit -m "update config tina cloud"
# Vê se tem alguma alteração na branch main remota
git pull origin main
# Envia as alterações para branch remota
git push origin main
Alterações enviadas para branch main remota, agora vamos verificar se as configurações estão ok para o Tina Cloud, no terminal, na raiz do seu site, execute:
# Checa configurações no Tina Cloud
npx tinacms build
Se tudo estiver ok, você verá 4 checks verdes
Lá na tela de projeto do Tina Cloud, se você for no menu Configuration, você verá que aparecerá a branch mainno bloco Branch Status.
Aparecendo isso, é sinal que toda configuração está ok.
Ajustando o deploy do site no Netlify Link para o cabeçalho
Para que o site possa puxar corretamente o TinaCMS, será precisa fazer alguns ajustes no deploy no Netlify.
Acesse o Netlify, selecione seu site que está configurando, depois no menu lateral esquerdo ou ao meio clique em Site configuration.
Na tela exibida, clique em Build & deploy.
Depois role a página até embaixo e clique em “Configure”
Procure o campo Buid command e substitua o comando por e clique no botão Save
npx tinacms build && hugo
Agora clique na opção Environment variables.
Na tela que aparece, clique em Add a variable, depois em import from a .env file
Copie o conteúdo do seu .env e cole no campo Content of .env file, depois clique em import variables
As variáveis sendo importadas, elas irão aparecer da seguinte forma na tela:
Agora vá no menu lateral esquerdo e clique em Deploy, depois na parte direita em Trigger e Deploy site.
Aguarde o deploy, isso demora alguns segundos, para que o site seja compilado já incluindo o TinaCMS.
Tudo ocorrendo bem, seu deploy vai aparecer com o status de Complete em todas as etapas.
O site agora já está integrado ao TinaCMS!
Agora vamos para a última parte.
Tina Cloud configurando domínio de acesso Link para o cabeçalho
Para acessar o TinaCMS em modo de produção é utilizado o Tina Cloud que serve de ponte para esse acesso.
No Tina Cloud será necessário configurar os domínios que tem permissão de acesso
O Netlify forneceu a seguinte URL de acesso para o site:
https://spontaneous-figolla-d5e343.netlify.app
Nesse caso já pego essa URL e vou lá no Tina Cloud, no menu Configuration do projeto e já defino essa URL para liberar o acesso para esse domínio
Agora vamos acessar a URL do site com /admin
No meu caso a URL ficou: https://spontaneous-figolla-d5e343.netlify.app/admin
Clique em Login in
Caso dê algum erro de URL
Copie a URL que aparece no campo origin=URL… que está presente na própria URL da janela de autenticação, exemplo:
Nesse exemplo, você copia apenas https://__main-spontaneous-figolla-d5e343.netlify.app
Volte lá no Tina Cloud, Configuration do seu projeto e adicione essa URL também.
Agora volte na tela de login e dê um refresh.
Tudo ocorrendo bem, você conseguirá acessar TinaCMS no modo de produção, já incluindo alguns campos com traduções e com a função de pesquisa já habilitada.
Agora você já pode escrever suas postagens e artigos utilizando esse ótimo CMS de uma forma bem prática e intuitiva🙂!
Em breve abordarei mais recursos sobre o assunto.
Código fonte desse tutorial
https://github.com/tiagotsc/hugo-tinacms
Comandos úteis
# COMANDOS HUGO
# Compila o site, o resultado fica diponível na pasta public
hugo
# Sobe o site localmente sem exibir postagens de rascunhos (padrão do Hugo)
hugo server
# Sobe o site localmente exibindo postagens de rascunhos
hugo server -D
# Sobe o site localmente deixando-o acesssível de qualquer dispositivo na rede
# Bom para acessar de outra máquina ou visualizar no celular
hugo server --bind 0.0.0.0 --baseURL http://0.0.0.0 --port 1313 -D
Ou
hugo server --bind=0.0.0.0 --baseURL=http://0.0.0.0:1313 -D
# Cria uma nova postagem
hugo new content content/posts/my-first-post.md
# Listar comandos
hugo -h
# Mais detalhes dos comandos na documentação oficial
https://gohugo.io/commands
# COMANDOS TINACMS
# Sobe TinaCMS junto com o site Hugo
npx tinacms dev -c "hugo server -D"
Links úteis
Documentação oficial do Hugo
https://gohugo.io/documentation
Documentação oficial TinaCMS
Caso queira personalizar ainda mais a pesquisa
https://tina.io/docs/reference/search/overview
Caso queira configurar e personalizar ainda mais os campos
https://tina.io/docs/reference/types
https://tina.io/docs/reference/fields
Caso queira customizar a forma como o arquivo de postagem é salvo