Durante muito tempo, quando eu pensava em FAQ no WordPress, a solução mais comum sempre parecia ser a mesma: criar um bloco específico, usar um plugin pronto ou adicionar campos separados para pergunta e resposta. Tudo isso funciona, mas em muitos casos também adiciona mais interface, mais complexidade e mais dependência de uma estrutura rígida.
Eu queria uma forma simples de permitir que uma pessoa editasse um post ou uma página normalmente no WordPress e, dentro desse conteúdo, conseguisse sinalizar o que era pergunta e o que era resposta sem precisar aprender uma interface nova, sem depender de blocos customizados e sem transformar a edição em algo travado.
Foi dessa necessidade que nasceu o Nousk FAQ, um plugin que interpreta marcações escritas diretamente no conteúdo e transforma esses trechos em um FAQ expansível no front-end.
Neste post eu quero mostrar a ideia por trás do plugin, como ele funciona, porque eu optei por usar parsing e porque, para mim, esse tipo de solução representa muito mais do que apenas um efeito de abrir e fechar respostas.
O que esse plugin representa para mim
Esse plugin não é importante só porque resolve um FAQ.
Ele é importante porque mostra uma mudança de mentalidade.
Em vez de pensar apenas em exibir dados, eu precisei pensar em como interpretar conteúdo, impor regras editoriais, validar estrutura, transformar texto em significado e só depois renderizar uma interface.
Esse tipo de projeto me interessa muito porque junta áreas que eu gosto de desenvolvimento.
Tem WordPress.
Tem arquitetura de plugin.
Tem validação.
Tem parsing.
Tem front-end.
Tem experiência de edição.
Tem semântica.
É o tipo de solução que nasce de um problema real e vai se sofisticando conforme a necessidade fica mais clara.
O problema que eu queria resolver
A necessidade parecia simples. Eu precisava de um FAQ.
Mas não queria um FAQ preso a uma interface pesada, cheia de campos separados, com uma experiência ruim para quem edita conteúdo no dia a dia. Em muitos cenários, a pessoa que escreve um post quer continuar usando o editor normal do WordPress, com texto antes, texto depois e um bloco específico de perguntas e respostas no meio.
Então a pergunta real não era “como criar um accordion no front”. Era: como permitir que o editor escreva conteúdo normalmente e, ao mesmo tempo, consiga sinalizar uma estrutura de FAQ de forma simples, previsível e validável.
Isso muda completamente o tipo de solução. Em vez de pensar primeiro no visual, eu precisei pensar em conteúdo, regras editoriais, validação e interpretação.
A ideia central do plugin
A base do plugin é simples. Quando o FAQ está ativado em um post ou página, o conteúdo pode conter marcações específicas:
nsk-faq-inicio:
nsk-perg:
nsk-resp:
nsk-faq-fim:
Essas marcações dizem ao plugin onde o FAQ começa, onde termina, o que é pergunta e o que é resposta.
Um exemplo de conteúdo seria assim:
Texto introdutório normal.
nsk-faq-inicio:
nsk-perg:
O que este plugin faz?
nsk-resp:
Ele transforma conteúdo marcado em um FAQ interativo.
nsk-perg:
Posso usar mais de um parágrafo?
nsk-resp:
Sim.
Pode usar vários parágrafos normalmente.
nsk-faq-fim:
Texto final do post.
No painel do WordPress, a pessoa escreve normalmente. No front-end, esse trecho é convertido automaticamente em um accordion.
Isso permitiu manter duas coisas muito importantes ao mesmo tempo: simplicidade para quem edita e controle técnico para quem desenvolve.
A pessoa não precisa mudar a forma de pensar na hora de escrever. Ela continua no editor de conteúdo, só que com uma convenção clara. O time editorial ganha autonomia. O desenvolvimento ganha uma estrutura previsível para interpretar. E o plugin fica menos dependente de uma interface complexa.
Além disso, existe um valor importante em transformar texto marcado em estrutura interpretável.
O papel do parser nessa solução
Se eu tivesse que resumir a função do parser de forma simples, eu diria o seguinte: O parser lê um conteúdo e entende que ali existem regras.
No caso desse plugin, o conteúdo do WordPress não é tratado só como um bloco de texto ou HTML. Ele é lido como algo que contém sinais de estrutura. O parser identifica essas marcações textuais e organiza o conteúdo em pares de pergunta e resposta.
Em vez de simplesmente exibir tudo como foi escrito, o sistema interpreta o que foi escrito. Esse ponto é importante porque muda a natureza da solução.
Sem parser, o plugin seria só um recurso visual.
Com parser, ele passa a ser um sistema que transforma conteúdo em estrutura.
Isso permite validar, organizar e renderizar de forma consistente.
E vale dizer que comecei esse codigo em 2020 e o parser não chegou de um dia pro outro. Passei pelo processo de só recurso visual. Cada passo que dei com essa funcionalidade me fez enxergar uma nova maneira de desenvolver com WordPress, e eu aprendi muito com todos os passos.
O que significa fazer parse nesse contexto
No plugin, fazer parse significa percorrer o conteúdo e encontrar padrões que tenham significado para a aplicação.
Esses padrões são as marcações que definem o início e o fim do FAQ e também as partes internas de pergunta e resposta.
A lógica do parser segue esta ideia:
Tudo que está entre `nsk-perg:` e a próxima `nsk-resp:` é uma pergunta.
Tudo que está entre `nsk-resp:` e a próxima `nsk-perg:` ou `nsk-faq-fim:` é uma resposta.
Essa decisão foi muito importante porque tornou o sistema mais robusto. Eu não queria depender da estrutura de <p> do conteúdo. Eu queria permitir múltiplos parágrafos, conteúdo mais livre e menos chance de erro por causa da forma como o editor organiza o HTML.
Por que delimitar o início e o fim do FAQ
Uma das decisões mais importantes do projeto foi exigir um marcador de início e um marcador de fim.
Isso deixa a estrutura mais segura.
Sem esse limite, o sistema precisaria adivinhar onde o FAQ começa e termina, e isso abre espaço para ambiguidades. Com os marcadores `nsk-faq-inicio:` e `nsk-faq-fim:`, a regra fica clara para o editor e também para o código.
Tudo que está fora desse bloco é tratado como conteúdo normal.
Tudo que está dentro desse bloco deve obedecer às regras do FAQ.
Esse tipo de separação evita interpretações erradas, reduz bugs e melhora muito a previsibilidade da solução.
E essa decisão veio depois…depois do parse até. Achei necessário esses marcadores e vi na prática a segurança que deu para os editores.
A importância da validação
A validação se tornou uma parte central do projeto. E só se tornou depois de cada passo dado. Era fundamental que o plugin não apenas interpretasse o conteúdo, porque cedo ou tarde o front-end iria quebrar.
Quando o FAQ está ativado, o conteúdo é validado antes de publicar ou atualizar. Se houver algum problema estrutural, o post não é publicado normalmente e fica como rascunho.
Essa etapa impede erros como:
- pergunta sem resposta
- resposta antes de pergunta
- conteúdo solto dentro do bloco FAQ
- bloco vazio
- pergunta vazia
- resposta vazia
- blocos FAQ aninhados (com hierarquia inconsistente)
- quantidade incorreta de marcações de início e fim
Não basta gerar o accordion. É preciso garantir que a estrutura seja válida antes de chegar ao front-end.
Por que conteúdo solto dentro do bloco FAQ é um problema
Isso foi uma decisão: dentro do bloco FAQ não pode existir texto solto antes da primeira pergunta. Parágrafos vazios são aceitos, mas texto sem marcação não.
Isso foi importante porque eu não queria um bloco misto. Se o sistema começa a permitir conteúdo aleatório dentro da área do FAQ, a estrutura perde clareza e a regra editorial enfraquece.
Quando o bloco FAQ começa, ele entra em um modo estrito. A primeira marcação válida precisa ser `nsk-perg:`. A partir daí, tudo precisa seguir a lógica de pergunta e resposta.
Múltiplos blocos FAQ no mesmo conteúdo
Outro ponto: o plugin não ficou limitado a um único FAQ por post.
Se o conteúdo tiver mais de um bloco entre `nsk-faq-inicio:` e `nsk-faq-fim:`, o sistema consegue processar todos eles.
Ao mesmo tempo, eu mantive uma regra importante: os blocos não podem ser aninhados, ou seja, pode haver vários blocos FAQ no mesmo conteúdo, mas um não pode existir dentro do outro.
Como o conteúdo é transformado no front-end
Depois de validar o conteúdo, o plugin intercepta o `the_content` (hook do WordPress responsável por filtrar o conteúdo antes de renderizar) e substitui cada bloco FAQ pelo HTML do accordion. No processo, as marcações desaparecem do front-end.
O usuário final não vê `nsk-faq-inicio:`, `nsk-perg:` ou `nsk-resp:`. Ele vê apenas a interface pronta, com perguntas clicáveis e respostas expansíveis.
O que o editor escreve serve como base estrutural. O que o visitante vê é a interface final construída a partir dessa estrutura.
Acessibilidade no accordion
Mesmo sendo uma primeira versão, eu quis garantir uma base de acessibilidade.
As perguntas são renderizadas como botões reais. Cada botão usa `aria-expanded` para indicar se o item está aberto ou fechado e `aria-controls` para associar o botão ao conteúdo que ele controla. As respostas usam `hidden` quando estão fechadas.
Isso melhora a navegação com teclado e ajuda tecnologias assistivas a entenderem a relação entre pergunta e resposta.
O que pode evoluir no futuro
A primeira versão já resolve muito bem o problema central. Mas existem várias possibilidades de evolução.
É possível adicionar opções visuais, como borda, ícones e variações de estilo.
Também dá para incluir animações mais suaves, permitir modos de comportamento diferentes e até adicionar dados estruturados para SEO em um segundo momento.
Essas melhorias são evolução de produto. A base já está pronta. E, para mim, isso é um sinal de que a primeira versão foi fechada no momento certo.
Conclusão
Criar esse plugin foi um exercício muito interessante de transformar conteúdo em estrutura e estrutura em interface. Eu considero que foi o ponto de virada da minha visão sobre WordPress.
O ponto mais importante não foi o efeito visual do accordion. O ponto mais importante foi construir um sistema que permitisse ao editor escrever de forma simples, ao plugin validar com segurança e ao front-end exibir tudo de maneira consistente.
E, no fim, isso é uma das coisas mais interessantes em desenvolvimento: quando o código deixa de só mostrar informação e passa a interpretar intenção.
