Um gestor de conteúdos entra no painel de administração, encontra uma página entre 50 outras, abre o editor, corrige um cabeçalho, guarda, regressa ao site e atualiza o separador. Seis cliques para uma única edição. Para o Grav CMS, existe uma solução simples: o plugin Editable with ContentTools incorpora um editor WYSIWYG diretamente na página do site. Abre a página, clica em «editar», corrige o texto e guarda-o novamente num ficheiro Markdown sem entrar no painel de administração.

O plugin não é atualizado desde 2022 (o autor descontinuou oficialmente o suporte), mas funciona de forma estável no Grav 1.7 e cobre o cenário básico de edição de páginas Markdown simples, sem lógica dinâmica. A instalação demora cinco minutos e, depois disso, editar texto no frontend torna-se muito mais fácil.

Segue-se um guia completo, da instalação aos direitos de acesso, com uma análise das limitações e uma alternativa (Fred).

💡 Visão geral rápida:

• Instale o plugin via GPM ou através de um arquivo zip e copie a configuração.
• Configure o git-sync para enviar as alterações para um repositório (opcional).
• Marque as áreas editáveis com o shortcode editable, usando nomes únicos.
• Conceda permissões site.editable aos utilizadores do frontend.
• Una as sessões de administração e frontend através de session.split: false.
• Tenha presente a limitação: apenas Markdown simples, sem Twig ou conteúdo dinâmico.

Instalação: via GPM ou manualmente

O plugin é instalado através do Gestor de Pacotes do Grav, o método padrão para qualquer extensão no Grav:

1
bin/gpm install editable-contenttools

Execute o comando a partir da pasta raiz do site (onde se encontra bin/). O GPM irá descarregar a versão mais recente e extraí-la para /user/plugins/editable-contenttools.

Em alternativa, pode instalar manualmente: descarregue o arquivo zip do GitHub, extraia-o para /user/plugins/ e renomeie a pasta para editable-contenttools (sem o sufixo -master). A estrutura deverá ficar assim: /user/plugins/editable-contenttools/editable-contenttools.php.

Copiar a configuração para um local seguro

Após a instalação, certifique-se de copiar o ficheiro de configuração para o diretório do utilizador:

1
cp user/plugins/editable-contenttools/editable-contenttools.yaml user/config/plugins/editable-contenttools.yaml

Este passo é importante: se as definições permanecerem na pasta do plugin, serão repostas quando atualizar via GPM. Uma abordagem alternativa é instalar através do painel de administração do Grav (Plugins → Adicionar), caso em que o sistema cria automaticamente a configuração em user/config/plugins/ e não é necessária nenhuma cópia manual.

Configuração: três opções de configuração

O ficheiro editable-contenttools.yaml contém três parâmetros:

1
enabled: true
2
git-sync: false
3
git-sync-mode: foreground

enabled ativa o plugin. Sem enabled: true, o editor não aparecerá no frontend, mesmo que as permissões sejam concedidas. O valor predefinido é true.

git-sync aciona a sincronização com um repositório Git após cada gravação. Só funciona quando o plugin Git Sync está instalado. Se o seu site reside em Git e pretende registar cada alteração no histórico, defina como true. Caso contrário, mantenha como false.

git-sync-mode determina se deve aguardar que a sincronização termine antes de devolver o controlo ao utilizador. foreground significa que o botão «Guardar» só é desbloqueado após a conclusão do commit e do push. background funciona de forma assíncrona, mas alguns servidores Linux podem ter problemas com processos em segundo plano. Para a maioria dos cenários, foreground é suficiente.

Marcação de áreas editáveis: o shortcode [editable]

O plugin não torna toda a página editável automaticamente. Define quais os blocos que podem ser editados usando o shortcode [editable]:

1
[editable]
2
## Section heading
3
 
4
Text that can be edited from the frontend.
5
[/editable]

Uma página pode conter qualquer número destas áreas. Cada área deve ter um nome único; caso contrário, o ContentTools não saberá onde guardar as alterações.

O parâmetro name: unicidade obrigatória

Por predefinição, o plugin atribui nomes automaticamente (region-0, region-1 e assim sucessivamente), mas é melhor especificar nomes significativos manualmente:

1
[editable name="hero-block"]
2
## Main heading
3
 
4
Text that can be edited.
5
[/editable]

Na primeira gravação através do frontend, o plugin adiciona automaticamente um parâmetro name ao shortcode, caso este esteja em falta. Na prática, é mais fácil especificar os nomes logo na marcação, pois isso simplifica a depuração (consegue ver qual o bloco que está a editar nas ferramentas de desenvolvimento do navegador).

Depois de marcar e gravar a página, visite o site como um utilizador com a permissão site.editable, clique no ícone do lápis à esquerda e edite o texto como faria num editor de texto normal. Mantenha a tecla Shift premida durante cerca de três segundos para realçar todas as regiões editáveis.

Pode experimentá-lo no site de demonstração do plugin (a gravação está desativada, Grav 1.7.46).

Direitos de acesso: frontend e backend

Para que um utilizador veja o ícone do lápis, precisa de permissões de edição. As regras diferem para utilizadores de frontend (gestores de conteúdo) e utilizadores de backend (administradores).

Utilizadores de frontend

O utilizador tem de conseguir iniciar sessão através do plugin Grav Login ou Private Grav. Depois, adicione o seguinte ao ficheiro de conta (user/accounts/username.yaml):

1
access:
2
  site:
3
    login: 'true'
4
    editable: 'true'

Sem a permissão site.editable, o ícone do lápis não aparece, mesmo que o utilizador tenha sessão iniciada e possua outros direitos.

Utilizadores de backend (administradores)

Por predefinição, o Grav separa as sessões do admin e do frontend. Para permitir que um administrador edite páginas diretamente no site (sem entrar no painel de administração), defina o seguinte em system.yaml (ou através do painel de administração em Configuração → Sistema):

1
session:
2
  split: false

Isto une as sessões: iniciar sessão no painel de administração concederá automaticamente acesso ao editor de frontend. O administrador também precisará da permissão admin.super ou admin.pages no seu ficheiro de conta.

Se o ícone não aparecer depois de iniciar sessão, verifique as definições de cache do admin:

1
admin:
2
  super: 'true'
3
  login: 'true'
4
  cache: 'false'

O parâmetro cache: false desativa a cache para o admin e pode resolver o problema do ícone invisível.

Limitações: o que o plugin não consegue fazer

O plugin funciona exclusivamente com Markdown simples. Esta é uma limitação arquitetural, não um bug: o ContentTools edita HTML no navegador e o plugin converte o HTML de volta para Markdown. Durante este processo, qualquer marcação dinâmica será corrompida. Não edite conteúdo através do ContentTools se este:

• for composto por templates Twig (por exemplo, páginas modulares: os blocos filhos são inseridos pelo pai de forma dinâmica e o plugin não consegue ver o seu código-fonte);
• for injetado por outros plugins (o Page Inject e plugins semelhantes inserem conteúdo de outras páginas, o que é um processo unidirecional);
• se alterar via JavaScript no navegador (sliders, acordeões e outros elementos interativos serão convertidos para HTML estático);
• contiver tags especiais do Grav Markdown (imagens com os parâmetros ?lightbox e ?resize serão danificadas durante a conversão de HTML → Markdown, pois os parâmetros de processamento desaparecerão).

As regras de segurança são simples:

• Mantenha imagens e shortcodes complexos fora das áreas editáveis.
• Mantenha as áreas pequenas: o número é ilimitado e 10 blocos pequenos são melhores do que um bloco grande com riscos.
• Teste numa cópia do artigo ou num ambiente de testes antes de dar acesso aos editores.
• Se notar diferenças na formatação do Markdown entre a versão com o ícone do lápis e a versão sem ele, mova esse fragmento para fora de [editable].

Alternativa: o plugin Fred

Se a funcionalidade do Editable com ContentTools não for suficiente, veja o Fred, um editor frontend mais recente para o Grav que também se baseia no ContentTools. Principais diferenças:

• Upload de imagens através de um diálogo (com rotação e processamento básico).
• Envolvimento automático de conteúdo através do evento onPageProcessed, exigindo menos marcação manual de shortcodes.
• Desenvolvimento ativo: o autor aceita issues no GitHub e continua a adicionar funcionalidades.

Instalação via clonagem do repositório para /user/plugins/fred:

1
cd user/plugins
2
git clone https://github.com/BugHunter2k/grav-plugin-fred.git fred

As permissões são definidas de forma semelhante: site.editor: true no ficheiro da conta de utilizador (nota: site.editor, e não site.editable).

Tanto o Editable com ContentTools como o Fred resolvem o mesmo problema: dão aos gestores de conteúdo uma ferramenta para edições rápidas sem entrar no painel de administração. O primeiro é adequado se precisar de uma ferramenta simples e comprovada para páginas Markdown, sem experimentações. O segundo funciona se quiser mais automatização e estiver preparado para as potenciais arestas de um desenvolvimento ativo.

Vídeo: como funciona o ContentTools

Uma demonstração de dois minutos da edição de uma página Grav no navegador: o autor mostra como as áreas editáveis são destacadas, as alterações são feitas e o conteúdo é guardado novamente em Markdown. Uma boa forma de ver o plugin em ação antes de instalar.

⁉️🤔 Perguntas frequentes

Porque é que o ícone do lápis não aparece após a instalação?

Verifique quatro coisas. Primeiro, enabled: true na configuração do plugin (user/config/plugins/editable-contenttools.yaml). Segundo, o utilizador deve ter a permissão site.editable no seu ficheiro de conta. Terceiro, para utilizadores de backend, session.split deve estar como false no system.yaml. Quarto, limpe a cache do Grav: bin/grav clear-cache. Normalmente, o problema está nas permissões ou nas sessões divididas.

Posso editar páginas modulares?

Não. As páginas modulares são montadas a partir de páginas filhas através de templates Twig, o que é um processo unidirecional: o plugin não consegue «desmontar» o resultado de volta em partes. No frontend vê o HTML final, mas a fonte (ficheiros Markdown separados dos módulos filhos) está localizada noutras pastas e o plugin não sabe onde guardar as alterações. Para páginas modulares, use a interface padrão de Administração do Grav.

O que acontece se deixar uma imagem dentro de [editable]?

As tags especiais do Grav Markdown para imagens (com parâmetros ?lightbox, ?resize, ?cropResize) serão danificadas durante a conversão de HTML para Markdown. A imagem em si permanecerá no lugar (a tag <img> converte-se para Markdown normal ![](url)), mas os parâmetros de processamento desaparecerão. Conclusão: mantenha sempre as imagens com parâmetros fora da área editável. Se uma imagem for simples (sem parâmetros), tecnicamente pode deixá-la dentro, mas na prática é mais seguro mover todos os elementos multimédia para fora de [editable].

O plugin foi abandonado pelo autor. É seguro usá-lo?

O autor anunciou oficialmente o fim do suporte em 2022, e o último commit data de agosto de 2024 (uma atualização de compatibilidade para o Grav 1.7). O plugin é estável no Grav 1.7 e não afeta componentes críticos de segurança: trabalha apenas com conteúdo Markdown e não tem acesso a operações do servidor. Se planeia fazer a transição para o Grav 2.0, considere ver o Fred ou aguardar por uma solução oficial de edição frontend (estão a ser discutidas novas abordagens baseadas no TinyMCE e no Prosemirror no fórum).

Qual é a diferença entre o Editable com SimpleMDE e a versão com ContentTools?

O Editable com SimpleMDE usa a mesma abordagem (edição frontend), mas em vez de um editor visual, fornece o editor Markdown SimpleMDE com pré-visualização ao vivo. Adequa-se a quem prefere escrever marcação manualmente e quer ver o resultado à direita do editor, em vez do modo WYSIWYG. Ambos os plugins são do mesmo autor (bleutzinn) e ambos foram abandonados desde 2022.

Vale a pena instalar um editor frontend para o Grav em 2026

Se o seu site corre em Grav 1.7, é composto por páginas Markdown simples e os gestores de conteúdo estão cansados de entrar no painel de administração para fazer um par de edições, instale o Editable com ContentTools. Cinco minutos para a instalação, configuração mínima e a edição torna-se uma operação de um clique. Abra a página, clique no lápis, corrija o texto, guarde. Sem procuras em listas de páginas, sem trocas de separadores.

Para novos projetos ou ao planear uma transição para o Grav 2.0 (é esperado um lançamento em 2026, embora não haja uma data exata), considere o Fred: é mais ativamente desenvolvido e tem maior probabilidade de receber compatibilidade com a segunda versão do CMS. Em qualquer caso, a edição frontend poupa dezenas de cliques e minutos de tempo em cada edição, o que é especialmente notório em sites com atualizações de conteúdo frequentes. Experimente num ambiente de teste e decida até que ponto esta abordagem acelera o seu fluxo de trabalho.