receita

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.

resposta curtaUm sumário automático lê os títulos H2 e H3 do conteúdo no filtro the_content, garante um atributo id em cada um e imprime uma lista de links âncora no topo. Em WordPress isso cabe em cerca de 40 linhas de PHP. O ganho é navegação e clareza de estrutura, não posição no Google.
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

  1. 01Decida a regra: níveis incluídos (H2 e H3), mínimo de itens (3) e onde aparece (topo do post).
  2. 02Percorra o HTML do conteúdo, dê um id único a cada título e colecione os itens.
  3. 03Monte uma lista dentro de um elemento nav com rótulo acessível.
  4. 04Ajuste o CSS para que o título não fique escondido sob um cabeçalho fixo.
  5. 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() e is_main_query() evitam que o sumário apareça em listagens, widgets e feeds que também chamam the_content.
  • A expressão regular captura h2 e h3 com atributos. O modificador s deixa 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?" em como-testar-o-resultado, e o laço acrescenta -2, -3 para títulos repetidos.
  • A prioridade 12 roda depois do wpautop padrã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.

  1. Abra um post com mais de três H2 e clique em cada item.
  2. 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.
  3. Teste um post com dois H2 de mesmo texto: os ids devem sair como titulo e titulo-2.
  4. Teste um post curto: o sumário não deve aparecer.
  5. Navegue só com o teclado (Tab): cada link recebe foco visível.
  6. Passe a URL no validador HTML do W3C e confirme que não há id duplicado.

Erros comuns e como desfazer

ErroSintomaCorreção
Sumário aparece na listagem do blogbloco repetido na homeconfira is_singular e in_the_loop
Título some sob o cabeçalho fixorolagem para na altura erradaaumente scroll-margin-top
Ids mudam a cada edição de títulolinks externos quebramgrave a âncora manualmente nos títulos importantes
Títulos com HTML interno quebram o textorótulo com tagso código usa wp_strip_all_tags no rótulo
Conflito com bloco de sumário do temaíndice duplicadodesative 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.
  • nav com aria-label.
  • scroll-margin-top testado 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

  1. the_content, WordPress Developer Resources (2026-10-14)
  2. sanitize_title(), WordPress Developer Resources (2026-10-14)
  3. in_the_loop(), WordPress Developer Resources (2026-10-14)
  4. scroll-margin-top, MDN Web Docs (2026-10-14)
  5. 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.