receita

Receita: links internos semânticos

Um mapa de termos e destinos, um filtro seguro sobre o HTML e uma auditoria de páginas órfãs.

resposta curtaLinks internos semânticos ligam páginas por significado: um termo no texto aponta para a página que o explica. Em WordPress, mantenha um mapa termo-destino, aplique-o com DOMDocument só em texto corrido, limite a poucos links por página e audite as páginas sem nenhum link de entrada. Revise o resultado; automação sem revisão gera âncoras ruins.
Neste texto

Que problema esta receita resolve?

Sites que crescem por publicação contínua acumulam páginas que ninguém linka. O Google recomenda que toda página importante receba link de ao menos uma outra página do site e que a âncora descreva o destino. Fazer isso à mão em centenas de posts não escala, e fazer com busca e substituição cega quebra HTML, linka dentro de títulos e repete a mesma âncora vinte vezes.

A receita parte da lógica de plugins de linkagem interna, silos e validação que Camillo Dantas desenvolveu. Esses plugins não são vendidos; aqui você recebe o método e o código para montar a sua versão e a auditoria que prova se funcionou.

Quando usar e quando não usar

Use quando existe um conjunto estável de páginas-destino (guias, termos, categorias) e muitos posts que mencionam esses assuntos sem linkar.

Não use:

  • para linkar por palavra-chave comercial genérica em todo o site. Âncora repetida em volume parece manipulação e não ajuda o leitor;
  • em conteúdo jurídico ou de saúde sem revisão humana dos links aplicados;
  • se o site tem poucas páginas. Neste caso, linke à mão.

Pré-requisitos

  • Lista de páginas-destino com um termo principal por página (um conceito, uma casa).
  • PHP com extensão DOM (habilitada na maioria das hospedagens).
  • WP-CLI para a auditoria (opcional, mas recomendado).
  • Nível: intermediário.

Passo a passo

  1. 01Monte o mapa: cada linha tem o termo como aparece no texto e a URL do destino.
  2. 02Aplique o mapa no filtro the_content, apenas em texto corrido, no máximo uma vez por termo e cinco links automáticos por página.
  3. 03Exclua título, link existente, código e a própria página de destino.
  4. 04Liste páginas órfãs com WP-CLI e linke-as manualmente a partir de posts relacionados.
  5. 05Revise uma amostra e ajuste o mapa.

O filtro

<?php
/**
 * Plugin Name: Links internos semânticos (receita)
 */

function rl_mapa_termos() {
	// Exemplo: termo => caminho relativo. Troque pelos seus.
	return apply_filters( 'rl_mapa_termos', array(
		'dados estruturados' => '/guia-dados-estruturados/',
		'Core Web Vitals'    => '/guia-core-web-vitals/',
		'sitemap'            => '/guia-sitemap/',
	) );
}

function rl_inserir_links( $html, $mapa, $caminho_atual, $max = 5 ) {
	if ( '' === trim( $html ) || ! class_exists( 'DOMDocument' ) ) {
		return $html;
	}

	$dom = new DOMDocument();
	libxml_use_internal_errors( true );
	$dom->loadHTML(
		'<?xml encoding="utf-8" ?><div id="rl-raiz">' . $html . '</div>',
		LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD
	);
	libxml_clear_errors();

	$xpath = new DOMXPath( $dom );
	$nos   = $xpath->query(
		'//div[@id="rl-raiz"]//text()[not(ancestor::a) and not(ancestor::h1) and not(ancestor::h2) and not(ancestor::h3) and not(ancestor::h4) and not(ancestor::code) and not(ancestor::pre) and not(ancestor::script) and not(ancestor::style)]'
	);

	$feitos = 0;
	$usados = array();

	foreach ( iterator_to_array( $nos ) as $no ) {
		if ( $feitos >= $max ) {
			break;
		}
		foreach ( $mapa as $termo => $destino ) {
			if ( isset( $usados[ $termo ] ) || untrailingslashit( $destino ) === untrailingslashit( $caminho_atual ) ) {
				continue;
			}
			$padrao = '/(?<![\p{L}\p{N}])' . preg_quote( $termo, '/' ) . '(?![\p{L}\p{N}])/iu';
			if ( ! preg_match( $padrao, $no->nodeValue, $achou, PREG_OFFSET_CAPTURE ) ) {
				continue;
			}
			$inicio = $achou[0][1];
			$texto  = $no->nodeValue;
			$antes  = substr( $texto, 0, $inicio );
			$meio   = $achou[0][0];
			$depois = substr( $texto, $inicio + strlen( $meio ) );

			$link = $dom->createElement( 'a', $meio );
			$link->setAttribute( 'href', esc_url( home_url( $destino ) ) );

			$pai = $no->parentNode;
			$pai->insertBefore( $dom->createTextNode( $antes ), $no );
			$pai->insertBefore( $link, $no );
			$pai->insertBefore( $dom->createTextNode( $depois ), $no );
			$pai->removeChild( $no );

			$usados[ $termo ] = true;
			$feitos++;
			break; // o nó original foi substituído; passe ao próximo.
		}
	}

	$raiz = $dom->getElementById( 'rl-raiz' );
	$saida = '';
	foreach ( $raiz->childNodes as $filho ) {
		$saida .= $dom->saveHTML( $filho );
	}
	return $saida;
}

add_filter( 'the_content', function ( $conteudo ) {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $conteudo;
	}
	$caminho = wp_parse_url( get_permalink(), PHP_URL_PATH );
	return rl_inserir_links( $conteudo, rl_mapa_termos(), $caminho );
}, 20 );

Decisões embutidas no código:

  • O XPath só alcança nós de texto fora de a, títulos, code, pre, script e style.
  • O limite $max e o conjunto $usados impõem um link por termo e cinco por página.
  • O padrão com (?<![\p{L}\p{N}]) e (?![\p{L}\p{N}]) evita linkar "sitemaps" dentro de "sitemaps-xml" ou parte de palavra, e funciona com acentos graças ao modificador u.
  • Se a página atual é o destino, o termo é ignorado.
  • Observação técnica: $achou[0][1] e substr trabalham em bytes, coerentes entre si porque a captura devolve deslocamento em bytes. Não misture com mb_substr.

Se o seu conteúdo usa blocos com HTML complexo, teste num ambiente de homologação antes: o saveHTML normaliza algumas marcações. Se preferir risco zero, grave o resultado no post_content só depois de revisar, em vez de aplicar em tempo de exibição.

Auditoria de páginas órfãs

Com WP-CLI, liste os posts publicados e conte quantas vezes cada URL aparece no conteúdo dos outros. Um comando simples para conferir um post específico:

wp db query "SELECT ID, post_title FROM wp_posts WHERE post_status='publish' AND post_type='post' AND post_content LIKE '%/guia-sitemap/%'" --skip-column-names

Para o site todo, um script wp eval-file orfas.php:

<?php
$posts = get_posts( array( 'post_type' => 'post', 'post_status' => 'publish', 'numberposts' => -1 ) );
$recebe = array();
foreach ( $posts as $p ) {
	$recebe[ $p->ID ] = 0;
}
foreach ( $posts as $origem ) {
	foreach ( $posts as $destino ) {
		if ( $origem->ID !== $destino->ID && false !== strpos( $origem->post_content, wp_parse_url( get_permalink( $destino ), PHP_URL_PATH ) ) ) {
			$recebe[ $destino->ID ]++;
		}
	}
}
foreach ( $recebe as $id => $n ) {
	if ( 0 === $n ) {
		WP_CLI::line( $id . "\t" . get_the_title( $id ) );
	}
}

Em sites com milhares de posts, esse laço duplo é lento; rode fora do horário de pico ou exporte o conteúdo e processe em outra ferramenta. O resultado é a lista de candidatas a receber links.

Como testar

Critério de sucesso: nenhum link novo aparece em título, código ou dentro de outro link; cada página recebe no máximo cinco links automáticos; a lista de órfãs diminui após o trabalho manual.

  1. Abra três posts diferentes e inspecione o HTML dos links inseridos.
  2. Procure <a> dentro de <a> com a busca do inspetor: não deve existir.
  3. Rode o rastreador Screaming Frog ou equivalente e confira "inlinks" por URL antes e depois.
  4. No Search Console, o relatório de links mostra os principais links internos; compare as páginas mais linkadas com o que você pretendia.
  5. Reveja a variedade de âncoras: o mesmo termo para a mesma URL é aceitável, mas não deve dominar todo o site.

Erros comuns e como desfazer

  • Mapa grande demais, com termos genéricos como "SEO": muitos links irrelevantes. Reduza para termos específicos.
  • Linkar a mesma URL com cinco âncoras diferentes na mesma página: um link por destino basta.
  • Aplicar em páginas de política e termos legais: restrinja por tipo de post.
  • Remover o filtro e esquecer o cache: limpe o cache de página depois de desativar.

Para desfazer, remova o arquivo; como a receita atua na exibição, o conteúdo salvo não muda. Se você optou por gravar no banco, restaure a partir das revisões do post ou do backup que deve existir antes de qualquer gravação em massa.

Checklist final

  • Mapa curto, com termos específicos.
  • Limite de links por página definido.
  • Exclusão de títulos, códigos e links existentes.
  • Amostra de dez páginas revisada à mão.
  • Lista de órfãs tratada.
  • Backup antes de gravar qualquer coisa no banco.

Onde se aprofunda

A estrutura de silos e a lógica de cobertura estão no mini-curso Links internos e silos e na trilha de SEO técnico. A receita de sumário automático trata da navegação dentro do post, e o hub de conteúdo por tópico cuida da página que reúne tudo. O catálogo dos plugins originais está em camillodantas.com.br/plugins.

Fontes

  1. Link best practices for Google, Google Search Central (2025-12-10)
  2. Links report, Google Search Console Help (2026-10-14)
  3. the_content, WordPress Developer Resources (2026-10-14)
  4. DOMDocument::loadHTML, PHP Manual (2026-10-14)
  5. WP-CLI eval-file, WordPress Developer Resources (2026-10-14)

Não sabe por onde começar?

Compare as opções e escolha a trilha pelo seu objetivo.