📝 Hugo - Integração de site com o DecapCMS

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 DecapCMS a um site feito em Hugo Framework que está hospedado no Netlify.

DecapCMS é um CMS bem versátil e flexível, pois possuí diversas opções de configuração, tanto para campos, estruturação dos arquivos de postagens entre outros.

Inclusive ele é multilíngue e com isso dá para botar ele em português e isso é algo que faremos aqui também.

Pré-requisitos:

NodeJS

Caso não tenha instalado, segue o link para baixar e instalar
https://nodejs.org/en/download/package-manager
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

Configurando o DecapCMS no modo local Link para o cabeçalho

Melhor opção para trabalhar localmente ou em desenvolvimento.

Na pasta raiz do seu site tem uma pasta chamada static. Dentro dessa pasta crie uma pasta com o nome de admin e dentro dela crie 3 arquivos:

index.html

Essa será a página para acessar o CMS.
config.yml

Toda a configuração e personalização dos recursos funcionais do CMS ficará aqui.
style.css

Aqui faremos algumas pequenas personalização para melhorar a visualização no preview do CMS.

Seu diretório deve static deve ficar assim:

static/
├── admin/
├──── config.yml
├──── index.html
├──── style.css

No arquivo index.html, coloque o conteúdo:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="robots" content="noindex" />
    <title>Content Manager</title>
    <!-- Include do script que habilita o Netlify Identity nesta página -->
    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
  </head>
  <body>
    <!-- Include do script que habilita o Netlify Identity nesta página -->
    <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
    <!-- Aplica o CSS personalizado -->
    <script>
      var PostPreview = createClass({
        render: function() {
          var entry = this.props.entry;
          return h('div', {},
            h('h1', {}, entry.getIn(['data', 'title'])),
            h('div', {"className": "text"}, this.props.widgetFor('body'))
          );
        }
      });
      CMS.registerPreviewTemplate("post", PostPreview);
      CMS.registerPreviewStyle("/admin/style.css");
    </script>
  </body>
</html>

Veja que na liha 6 foi adicionado a tag para que essa página não seja indexada pelos robôs de SEO.

No arquivo config.yml, coloque o conteúdo:

local_backend: true # Habilita o DecapCMS para usar localmente
locale: 'pt' # Traduz o CMS para português. É preciso instalar o pacote npm i decap-cms-app
backend:
  name: git-gateway
  branch: main # Branch que será manipulada
media_folder: static/img # Pasta caminho absoluto onde os arquivos enviados vão residir
public_folder: /img # Pasta caminho relativo onde os arquivos enviados vão residir
sortable_fields: ['date', 'title'] # metadados que serão usado na ordenados
collections:
  - name: 'post' # Usado nas rotas do cms, ex.: /admin/collections/post
    label: 'Postagem' # Label usada na UI
    folder: 'content/posts' # Caminho para a pasta onde as postagens são gravadas
    create: true # Permite que usuário criem novos documentos nessa coleção
    slug: '{{slug}}' # Slug de artigo para URL, ex.: artigo1 que na URL ficaria tipo: http://blog.com/artigo1
    sort: "date:desc" # Ordenação padrão por data decrescente na data de publicação
    editor:
      preview: true # Habilita pré visualização
    fields: # Campos que serão editados no CMS
      - { label: 'Título', name: 'title', widget: 'string' }
      - { label: 'Data publicação', name: 'date', widget: 'datetime', format: 'YYYY-MM-DDTHH:mm:ss }
      - { label: 'Descrição', name: 'description', widget: 'string' }
      - { label: "Imagem capa", name: "image", widget: "image", required: false }
      - { label: "Rascunho", name: "draft", widget: "boolean", default: false }
      - { label: "Tags", name: "tags", widget: "list", default: [] }
      - { label: "Autores", name: "authors", widget: "list" }
      - { label: "Categorias", name: "categories", widget: "list" }
      - { label: 'Conteúdo', name: 'body', widget: 'markdown' }
  - name: 'pages'
    label: 'Páginas'
    folder: 'content'
    update: true # Pode atualizar página
    delete: false # Não pode deletar página
    slug: '{{slug}}'
    editor:
      preview: true
    fields:
      - { label: 'Título', name: 'title', widget: 'string' }
      - { label: "Conteúdo", name: "body", widget: "markdown" }

No arquivo style.css, coloque o conteúdo:

/**
Espaçamento entre linhas para melhorar a visualização
**/
.frame-content {
    font-family: Arial, Helvetica, sans-serif;
    line-height: 1.9rem;
}

/**
Expande as imagens no visualizador
**/
.frame-content img {
    max-width: 100%;
}

Agora no terminal, na raiz do seu site, rode os comandos:

# No meu caso faço uso do fnm para versionar o NodeJs, então preciso rodar
# Talvez na sua máquina não precise desse comando
fnm env --use-on-cd | Out-String | Invoke-Expression

# instalar o pacote de tradução do DecapCMS
npm i decap-cms-app

# Instala servidor DecapCMS para rodar localmente
npm i decap-server

# Inicia o servidor para prover o DecapCMS
npx decap-server
# O servidor ficará rodando na porta 8081

Deixe o servidor DecapCMS rodando, abra outro terminal, nas pasta raiz do seu site, rode:

# Inicia o servidor para prover o site
hugo server -D

Agora acesse a parte admin do DecapCMS, através do link

http://localhost:1313/admin

DecapCMS - local

Você verá o DecapCMS já todo traduzido e com as opções de filtros devidamente configuradas.

Todas essas configurações foram feitas no arquivo config.xml e caso necessário você pode ir ajustando de acordo com a sua necessidade.

Com os passos que você seguiu até aqui, você já consegue criar e editar localmente suas postagens nesse excelente CMS.

Caso queira encerrar os serviços, é só voltar no terminar e pressionar as teclas CTRL + C.

Envie esse código para o Github para a branch main, pois é ela que será utilizada em todo o processo do DecapCMS de produção.

# Adiciona alterações no git
git .

# Registra as alterações no git
git commit -m "update DecapCMS"

# Envia para a branch main remota
git push origin main

Configurando o DecapCMS no modo produção Link para o cabeçalho

Para que a gente possa prosseguir, volte no arquivo static\admin\config.yml, e faça a mudança:

# Mude o parâmetro
local_backend: true

# Para
local_backend: false

Assim você desabilita a execução local do DecapCMS.

Caso ainda esteja rodando os serviços locais, você pode cancelar com as teclas CTRL + C.

Nosso foco agora vai ser no nosso site que está hospedado no Netlify.

Configurando o Netlify Link para o cabeçalho

Logue no Netlify, vá no seu site, clique em Site configuration, depois em Importing an existing project:

Netlify - iniciando configuração

Na próxima tela procure a opção Identity e clique nela:

Netlify - iniciando configuração do identity

Agora vamos começar a configurar o processo de autenticação para nosso DecapCMS e para isso vamos usar o serviço Identity que funciona muito bem e já traz tudo pronto sem a necessidade de realizar o desenvolvimento e implementação de toda uma aplicação de autenticação.

Na tela que surge clique em Enable identity:

Netlify - habilitando identity

O Identity do Netlify é muito versátil e possibilita diversas formas de se configurar o acesso a sua aplicação que no nosso caso é nosso gerenciar de conteúdo DecapCMS.

Vamos usar o Git Gateway para ter permissão para criar arquivos no nosso repositório, que no caso serão as postagens, e ainda faremos a integração do provedor externo que no nosso caso será o Google para autenticação.

Assim conseguiremos amarrar nossa aplicação de CMS de ponta a ponta com bastante segurança.

Na tela que aparece clique em Service:

Netlify - service github

Depois clique em Enable Git Gateway:

Netlify - habilita gateway git

Dessa forma o nosso CMS terá permissão para criar e editar arquivos no nosso repositório do Github.

Com isso toda vez que a gente criar uma postagem no nosso CMS, os novos arquivos vão direto para o nosso repositório Github e como o Netlify já está integrado com CI/CD, ele vai puxar essas mudanças automaticamente e vai disponibilizar no nosso site.

Agora procure e clique na opção Registration:

Netlify - opção registration

Na tela que surge no bloco Registration preferences, clique em Configure, depois selecione a opção Invite only e clique em Save:

Netlify - definindo apenas convidados

Dessa forma apenas pessoas que recebem nosso convite terão acesso a parte administrativa do nosso CMS.

Depois ainda na mesma tela, clique na opção External providers e selecione o Google, na janela que surge mantenha a opção padrão marcada e clique em Enable Google:

Netlify - seleção external providers

Veja que existe várias opções de autenticação com provedor externa, mas utilizaremos o Google, pois é o mais popular.

Agora para que a pessoa tenha acesse ao nosso CMS, basta que nós enviemos o convite para ela.

Ainda na mesma tela role um pouco mais para cima e clique na opção Invite users, e na janela que abre, informe o seu email Gmail e clique em Send:

Netlify - enviando convite de acesso

Acesse sua caixa de email Gmail e você deve ter recebido um email parecido com o abaixo:

Netlify - email

Clique no link Accept the invite para aceitar o convite.

Você será direcionado para a tela do seu site.

Agora no navegador, edite a URL do seu site para https://ENDEREÇO-SEU-SITE/admin e aperte Enter para ir para autenticação.

Na tela que surge, antes de prosseguir, aperte CTRL + F5 para limpar o cache do navegador e assim pegar as novas configurações.

Agora clique no botão Entrar com Netlify Identity

Na janela que abre clique em Continue with Google:

DecapCMS - login Google

Tudo ocorrendo bem, você irá visualizar a parte administrativa do DecapCMS já no Netlify.

DecapCMS - adm no Netlify

Agora você já pode escrever seus artigos e postagens de forma segura de qualquer dispositivo, basta você estar conectado na internet.

Inclusive, você pode mandar convites para outras pessoas para que elas possam escrever artigos junto com você🙂!

Em breve abordarei mais recursos sobre o assunto.

Código fonte desse tutorial

https://github.com/tiagotsc/hugo-decapcms

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 DECAPCMS

# Rodar DecapCMS localmente
# "local_backend: false" precisa estar definido no static\admin\config.yml
npx decap-server