Receita: sumário automático por títulos
Gere um índice clicável a partir dos H2 e H3 de cada post, com âncoras estáveis e sem plugin.
Neste texto
Que problema esta receita resolve?
Artigos longos perdem o leitor que procura uma parte específica. Um sumário no topo deixa visível a estrutura, permite pular para a seção certa e, de quebra, obriga o autor a escrever títulos que descrevem o que vem abaixo. O mesmo vale para quem lê a página por máquina: títulos hierárquicos bem formados e âncoras estáveis tornam cada seção endereçável por uma URL com fragmento.
Camillo Dantas desenvolveu plugins de geração de sumário e de menu por títulos. Eles não são vendidos. Esta receita ensina a inteligência por trás deles, para você montar a sua versão e entender cada decisão.
Um aviso de expectativa: o sumário não melhora ranking por si só. O que ajuda é a estrutura de títulos que ele expõe. Se os H2 forem vagos ("Introdução", "Mais informações"), o índice será vago também.
Quando usar e quando não usar
Use em posts com pelo menos três seções de H2, normalmente a partir de 800 palavras, em guias, tutoriais e páginas de referência.
Não use:
- em textos curtos, onde o índice ocupa mais espaço que o conteúdo;
- em páginas cujo tema (ou page builder) já gera âncoras próprias, para não duplicar o bloco;
- quando os títulos são decorativos. Primeiro conserte os títulos.
Pré-requisitos
- Posts escritos com títulos H2 e H3 reais (no editor de blocos, o bloco Título), não parágrafos em negrito.
- Um mu-plugin ou plugin próprio para o código.
- Tema que respeite o filtro
the_content(todo tema correto). - Nível: iniciante a intermediário.
Passo a passo
- 01Decida a regra: níveis incluídos (H2 e H3), mínimo de itens (3) e onde aparece (topo do post).
- 02Percorra o HTML do conteúdo, dê um id único a cada título e colecione os itens.
- 03Monte uma lista dentro de um elemento nav com rótulo acessível.
- 04Ajuste o CSS para que o título não fique escondido sob um cabeçalho fixo.
- 05Teste com um post longo, um curto e um com títulos repetidos.
O código
Arquivo wp-content/mu-plugins/sumario-automatico.php:
<?php
/**
* Plugin Name: Sumário automático (receita)
*/
add_filter( 'the_content', function ( $conteudo ) {
if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
return $conteudo;
}
$itens = array();
$usados = array();
$conteudo = preg_replace_callback(
'/<h([23])([^>]*)>(.*?)<\/h\1>/is',
function ( $m ) use ( &$itens, &$usados ) {
$nivel = (int) $m[1];
$attrs = $m[2];
$texto = trim( wp_strip_all_tags( $m[3] ) );
if ( preg_match( '/\sid=["\']([^"\']+)["\']/i', $attrs, $id ) ) {
$slug = $id[1];
} else {
$slug = sanitize_title( $texto );
if ( '' === $slug ) {
$slug = 'secao';
}
$base = $slug;
$n = 2;
while ( isset( $usados[ $slug ] ) ) {
$slug = $base . '-' . $n++;
}
$attrs .= ' id="' . esc_attr( $slug ) . '"';
}
$usados[ $slug ] = true;
$itens[] = array( 'n' => $nivel, 'id' => $slug, 't' => $texto );
return '<h' . $nivel . $attrs . '>' . $m[3] . '</h' . $nivel . '>';
},
$conteudo
);
if ( count( $itens ) < 3 ) {
return $conteudo;
}
$html = '<nav class="sumario" aria-label="Sumário do artigo"><p class="sumario__titulo">Neste artigo</p><ol>';
foreach ( $itens as $i ) {
$html .= '<li class="nivel-' . (int) $i['n'] . '"><a href="#' . esc_attr( $i['id'] ) . '">' . esc_html( $i['t'] ) . '</a></li>';
}
$html .= '</ol></nav>';
return $html . $conteudo;
}, 12 );
O que cada trecho faz:
is_singular( 'post' ),in_the_loop()eis_main_query()evitam que o sumário apareça em listagens, widgets e feeds que também chamamthe_content.- A expressão regular captura
h2eh3com atributos. O modificadorsdeixa o ponto atravessar quebras de linha. - Se o título já tem
id(o editor de blocos grava âncora quando você preenche o campo "Âncora HTML"), o código reaproveita. Isso protege links externos que já existem. sanitize_title()converte "Como testar o resultado?" emcomo-testar-o-resultado, e o laço acrescenta-2,-3para títulos repetidos.- A prioridade 12 roda depois do
wpautoppadrão (10) e de outros filtros comuns. Se algum plugin de bloco alterar títulos depois, ajuste o número.
O CSS
html { scroll-behavior: smooth; }
h2[id], h3[id] { scroll-margin-top: 5rem; }
.sumario { border: 1px solid #d8dde0; padding: 1rem 1.25rem; margin: 0 0 2rem; }
.sumario ol { margin: 0; padding-left: 1.25rem; }
.sumario .nivel-3 { margin-left: 1rem; list-style-type: circle; }
@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
scroll-margin-top compensa um cabeçalho fixo; ajuste o valor à altura real do seu tema. A regra prefers-reduced-motion respeita quem desativa animações no sistema.
Como testar
Critério de sucesso: todo item do sumário leva ao título certo, nenhum id se repete e a página não gera erro no validador HTML.
- Abra um post com mais de três H2 e clique em cada item.
- No console do navegador, rode
[...document.querySelectorAll('[id]')].map(e=>e.id).filter((v,i,a)=>a.indexOf(v)!==i). A lista deve voltar vazia. - Teste um post com dois H2 de mesmo texto: os ids devem sair como
tituloetitulo-2. - Teste um post curto: o sumário não deve aparecer.
- Navegue só com o teclado (Tab): cada link recebe foco visível.
- Passe a URL no validador HTML do W3C e confirme que não há id duplicado.
Erros comuns e como desfazer
| Erro | Sintoma | Correção |
|---|---|---|
| Sumário aparece na listagem do blog | bloco repetido na home | confira is_singular e in_the_loop |
| Título some sob o cabeçalho fixo | rolagem para na altura errada | aumente scroll-margin-top |
| Ids mudam a cada edição de título | links externos quebram | grave a âncora manualmente nos títulos importantes |
| Títulos com HTML interno quebram o texto | rótulo com tags | o código usa wp_strip_all_tags no rótulo |
| Conflito com bloco de sumário do tema | índice duplicado | desative um dos dois |
Para desfazer, remova o arquivo do mu-plugin. Os conteúdos não são alterados no banco, porque o filtro age só na exibição.
Checklist final
- Mínimo de três itens para exibir.
- Ids únicos e estáveis.
navcomaria-label.scroll-margin-toptestado com o cabeçalho real.- Sem sumário em listagens e feeds.
- Títulos reescritos para descrever o conteúdo da seção.
Próximos passos
O sumário funciona melhor quando o artigo também recebe links internos bem pensados: veja a receita de links internos semânticos e a de hub de conteúdo por tópico. Para treinar estrutura de títulos e silos, o mini-curso Links internos e silos cobre o assunto com exercícios. Como o texto deve ser escrito para ser entendido por pessoas e sistemas, o curso Conteúdo para IA na prática detalha o método. Os plugins originais estão descritos em camillodantas.com.br/plugins.
Fontes
- the_content, WordPress Developer Resources (2026-10-14)
- sanitize_title(), WordPress Developer Resources (2026-10-14)
- in_the_loop(), WordPress Developer Resources (2026-10-14)
- scroll-margin-top, MDN Web Docs (2026-10-14)
- Link best practices for Google, Google Search Central (2025-12-10)
Não sabe por onde começar?
Compare as opções e escolha a trilha pelo seu objetivo.