Índice: Formato e Regras

Na biblioteca de elementos , uma visão geral rápida e um índice informam aos leitores o que uma página cobre, no que ela os ajudará a decidir e como pular para a seção que precisam.

Visão geral rápida. Use este elemento de abertura emparelhado em páginas longas ou estruturalmente complexas. Escreva uma visão geral de 40 a 90 palavras que defina o escopo e o resultado esperado, depois forneça uma lista de conteúdo feita a partir de cabeçalhos H2 estáveis e apenas cabeçalhos H3 úteis. Neste site, o controle de conteúdo dinâmico abaixo permanece oculto até que o leitor tenha rolado mais de 300 pixels; ele então aparece como um menu suspenso fixo no desktop abaixo do cabeçalho do site.

Por que este elemento é importante

Os leitores não começam toda página longa no mesmo ponto. Uma pessoa precisa de uma definição, outra quer etapas de implementação e uma terceira está verificando uma única restrição antes de aprovar o trabalho. Uma breve visão geral responde “Estou no lugar certo?” antes que o leitor invista atenção. A lista de conteúdo responde “Onde está a parte que preciso?” sem forçar uma leitura linear.

As duas partes são especificadas juntas porque resolvem problemas de orientação adjacentes, porém diferentes. A visão geral explica a promessa, os limites e o resultado útil da página em frases. A lista de conteúdo expõe o caminho através dessa promessa como destinos. Uma lista de conteúdo sem visão geral pode mostrar que uma página tem seções chamadas “Configuração” e “Acessibilidade”, mas não consegue explicar se a página é uma introdução conceitual ou uma especificação de produção. Uma visão geral sem navegação pode estabelecer escopo, mas ainda obriga o leitor a percorrer 3.000 palavras.

Este elemento também melhora a capacidade de extração por máquinas, ou seja, a capacidade do software de isolar uma passagem e reter seu propósito fora da página completa. A visão geral é um segundo resumo conciso e autocontido após o título e a descrição. O índice fonte do Hugo é um esboço vinculado e legível por máquina da cobertura e hierarquia da página; o renderizador fixo atual converte esses links em opções que retêm seus valores de fragmento de URL, a parte #secao de uma URL. Sistemas de busca, ferramentas de recuperação, extensões de navegador e agentes de IA podem usar o esboço do documento para identificar regiões prováveis de resposta antes de processar cada parágrafo. Isso não garante um recurso de busca ou citação por IA; reduz a ambiguidade sobre onde os assuntos começam e como se relacionam.

O emparelhamento não deve criar repetição. Uma visão geral declara escopo e resultado. Um bloco de resposta direta responde à pergunta principal. As principais conclusões declaram conclusões que valem a pena lembrar. Quando todos os três dizem a mesma coisa em caixas diferentes, a abertura se torna um obstáculo em vez de uma ajuda.

Quando usar

A lista de conteúdo ganha seu lugar quando pular é um comportamento provável do leitor. A contagem de palavras é um indicador útil, mas a estrutura é o fator decisivo.

Use apenas a visão geral quando o título puder ser interpretado de forma ampla, quando a página excluir deliberadamente assuntos adjacentes ou quando o leitor precisar saber o resultado esperado antes de prosseguir. Uma página de política de 900 palavras pode precisar de uma visão geral de duas frases, mesmo que não precise de navegação.

Use apenas a lista de conteúdo quando o título e a abertura já tornarem o escopo inconfundível. Essa proximidade é comum em páginas de referência: a abertura pode conter uma definição direta que cumpre o papel de orientação, enquanto um longo conjunto de campos independentes ainda precisa de navegação.

Não use nenhuma das partes como decoração. Um TOC de seis itens em um artigo de 700 palavras adiciona uma decisão extra antes da resposta. Uma visão geral que diz “Este guia explora tudo que você precisa saber” não define escopo, resultado ou exclusões. Não use o par para ocultar uma estrutura de cabeçalhos fraca: se os cabeçalhos se sobrepõem, usam gramática inconsistente ou dividem uma ideia em muitas seções minúsculas, corrija o documento antes de expor seu esboço.

Onde posicionar

A posição faz parte do significado do elemento. A visão geral deve aparecer após o herói ou a resposta direta de abertura e antes do primeiro H2. Pode ser um parágrafo curto ou uma lista compacta, mas deve ser encontrada antes que o leitor se comprometa com o corpo. A invocação do TOC pertence imediatamente após a visão geral, para que a fonte autoral mantenha orientação e navegação juntas, mesmo que o controle fixo deste site só se torne visível após rolar 300 pixels.

O par não pode interromper uma definição, separar uma afirmação de sua evidência ou aparecer pela primeira vez no meio do documento. Não o coloque entre um cabeçalho e o parágrafo de abertura desse cabeçalho: a relação entre cabeçalho e explicação deve permanecer direta. Não coloque outro componente do tipo visão geral imediatamente ao lado. Quando um bloco de resposta direta ou de principais conclusões for necessário, atribua funções distintas e use esta ordem: resposta direta, visão geral curta de escopo, invocação do TOC, primeira seção do corpo. Omita um dos resumos se a redação ainda se sobrepuser.

Use o shortcode uma vez por página. Seus IDs renderizados (tocDropdown, tocSelect, selectTrigger e controles relacionados) são fixos, portanto, uma segunda instância cria IDs de documento duplicados e scripts imprevisíveis.

Anatomia

O elemento tem seis regiões significativas. As primeiras cinco são de conteúdo ou comportamento; o indicador de progresso é de status. A legenda é mantida na página para que permaneça legível quando a captura de tela for redimensionada ou substituída.

1. Corpo da visão geral: 40 a 90 palavras declarando escopo, resultado pretendido e qualquer limite importante.
2. Título do wrapper fixo: o título da página por padrão, ou o atributo title criado quando um rótulo mais curto for mais claro.
3. Rótulo da seção atual: começa como “Selecione a seção…” e muda à medida que o IntersectionObserver do navegador, uma API que detecta elementos entrando em uma região definida da viewport, marca seções como ativas.
4. Gatilho do menu suspenso: abre a lista gerada de destinos de seção ao clicar na implementação atual.
5. Opções de cabeçalho: links derivados do índice de páginas do Hugo, atualmente H2 e H3 devido a markup.toml.
6. Barra de progresso: mostra a proporção do documento rolável total percorrido; não identifica a conclusão de seção.

Exemplos de design

A galeria cobre estados de comportamento em vez de temas decorativos. O conteúdo subjacente permanece o mesmo para que revisores possam comparar temporização, hierarquia, corte e interação.

Nenhuma variante visual alternativa é criada via Markdown. title altera o rótulo e class adiciona classes ao wrapper, mas nenhum cria um elemento semanticamente diferente. Novos tratamentos de cor, cartão, barra lateral ou lista inline exigem uma decisão de componente em vez de uma classe arbitrária adicionada no conteúdo.

Parâmetros

A visão geral e o TOC compartilham um contrato editorial, mas apenas o TOC fixo é renderizado pelo shortcode atual. Os valores de configuração são incluídos porque alteram a saída, embora os autores não possam defini-los por invocação.

A dependência é fácil de perder: uma página sem cabeçalhos H2 renderiza silenciosamente nenhum TOC fixo porque o Hugo não produz um esboço utilizável e o partial emite marcação apenas quando tem cabeçalhos. Com a configuração atual, H2 e seus descendentes H3 são elegíveis; H4 e cabeçalhos mais profundos são excluídos. O partial normalmente analisa o .TableOfContents do Hugo. Seu fallback HTML escaneia apenas elementos H2 renderizados, portanto, os autores não devem confiar no comportamento de fallback para preservar a navegação H3.

Sintaxe e exemplos de código

A notação portável mantém a visão geral como o corpo do elemento e as configurações de navegação como atributos. Os links de cabeçalho permanecem gerados a partir do documento circundante, em vez de duplicados pelo autor.

:::quick-overview-and-toc{title="Nesta página" class=""}
Este guia explica quando usar o elemento, como o controle fixo do Hugo se comporta
e como preservar destinos de seção acessíveis e estáveis após a publicação.
:::

O mapeamento atual do Hugo escreve a visão geral como Markdown normal e invoca o shortcode fornecido uma vez. Não há corpo JSON.

Este guia explica quando usar o elemento, como o controle fixo do Hugo se comporta
e como preservar destinos de seção acessíveis e estáveis após a publicação.

{{< table-of-contents title="Nesta página" class="" >}}

O mapeamento do bloco WordPress armazena o mesmo corpo e atributos. Um site que não registrou o bloco pode usar o formulário de shortcode equivalente; não deve criar manualmente os links de cabeçalho.

<!-- wp:amicited/quick-overview-and-toc {"title":"Nesta página","className":""} -->
<p>Este guia explica quando usar o elemento, como o controle fixo se comporta
e como preservar destinos de seção acessíveis e estáveis após a publicação.</p>
<!-- /wp:amicited/quick-overview-and-toc -->

[amicited_quick_overview_toc title="Nesta página" class=""]
Este guia explica o escopo, comportamento e política de âncoras do elemento.
[/amicited_quick_overview_toc]

Nos três sistemas, a fonte da verdade é a hierarquia real de cabeçalhos do documento. Uma lista mantida manualmente se desviará à medida que os cabeçalhos mudarem e pode apontar para IDs que não estão mais presentes.

Exemplos

Exemplo bom

Visão geral rápida. Este guia mostra às equipes de conteúdo como planejar, escrever, revisar e manter uma página de comparação. Abrange padrões de evidência, critérios de comparação, afirmações sobre produtos, tabelas acessíveis e verificações pós-publicação. Não abrange colocação paga ou termos de comissão de afiliados.

Nesta página: Definir a decisão · Selecionar critérios de comparação · Reunir evidências · Redigir a página · Revisar afirmações · Medir e manter

Isso funciona porque a visão geral nomeia o público, o resultado, a cobertura e o limite em 48 palavras. Os seis destinos são tarefas distintas que um leitor pode revisitar independentemente. Seus rótulos usam frases verbais paralelas, então tanto pessoas quanto máquinas podem inferir um processo. Nenhuma das entradas repete o título da página ou expõe uma subseção trivial.

Exemplo ruim

Visão geral: Bem-vindo ao nosso guia completo. No mundo em mudança de hoje, há muito o que saber, então continue lendo para aprender tudo.

Conteúdo: Introdução · Mais informações · Coisas importantes · Outras coisas · Conclusão

Isso falha por dois motivos. A visão geral gasta 22 palavras sem definir escopo, leitor, resultado ou exclusão. As entradas rotulam contêineres retóricos em vez de assuntos, portanto não ajudam um leitor a prever onde uma resposta se encontra. Adicionar mais cabeçalhos não resolveria; o documento precisa de limites de seção significativos primeiro.

Um segundo erro comum é uma resposta de 600 palavras com “Visão geral”, “Contexto”, “Detalhes”, “Dicas” e “Conclusão” em seu TOC. Mesmo que cada âncora funcione, a lista adiciona mais interface do que valor de navegação. Mantenha a abertura direta e remova o TOC.

Marcação schema e acessibilidade

Aqui, marcação schema significa código padronizado legível por máquina que identifica entidades e propriedades. Este elemento não possui tipo ou propriedade dedicada no vocabulário Schema.org, e o shortcode do Hugo não emite JSON-LD, a notação baseada em script comumente usada para publicar esse vocabulário. Não marque o TOC como ItemList apenas por ser uma lista; isso sugeriria uma lista de itens de assunto em vez de navegação. A visão geral pode informar a description de uma página apenas quando a redação for independentemente adequada, mas não é copiada automaticamente para dados estruturados.

O comportamento HTML e ARIA é mais importante aqui. ARIA, o padrão Accessible Rich Internet Applications, fornece funções, nomes e estados quando o HTML nativo não o faz. Um landmark é uma região nomeada da página para a qual usuários de tecnologia assistiva podem pular. Foco é o alvo atual de interação do teclado.

Estes são fatos de implementação, não permissão para ignorar acessibilidade. Revisores de conteúdo podem verificar clareza dos cabeçalhos, IDs únicos e ordem lógica hoje. Os responsáveis pelo componente devem resolver o comportamento do gatilho, landmark, foco, URL e movimento reduzido antes de descrever a variante fixa como acessível por teclado.

Regras de redação

Escreva a visão geral depois que a estrutura da página estiver estável. Isso evita que uma promessa precoce se afaste da cobertura final. Mantenha entre 40 e 90 palavras. Prefira duas ou três frases; use três a cinco marcadores apenas quando a página contiver vários resultados genuinamente paralelos. Declare no que a página ajuda o leitor a entender, decidir ou fazer. Nomeie uma exclusão quando o título puder razoavelmente prometer mais do que a página entrega.

Use H2 para as principais perguntas, estágios ou áreas de decisão da página. Inclua H3 na navegação apenas quando for um destino independente útil dentro de um H2 substancial. Neste site, a configuração inclui automaticamente todo H2 e H3, portanto a política prática é mais rigorosa: não crie um cabeçalho a menos que ele mereça aparecer na navegação. Busque de 5 a 18 entradas no total. Se a lista gerada exceder 18, combine seções sobrepostas, remova cabeçalhos H3 desnecessários ou divida a página. Nunca pule diretamente de H2 para H4 para ocultar um cabeçalho do TOC; níveis de cabeçalho expressam hierarquia, não estilo ou preferência de navegação.

Use texto de cabeçalho conciso e descritivo. Um leitor deve entender cada destino sem ler seu parágrafo pai. Prefira formas paralelas dentro de uma sequência: “Escolher critérios”, “Reunir evidências” e “Revisar afirmações” são mais fáceis de escanear do que uma mistura de substantivos, perguntas e rótulos vagos. Não coloque citações, afirmações promocionais, emojis, selos de status ou frases completas em um cabeçalho apenas para influenciar o TOC.

A visão geral nunca deve conter uma segunda lista de conteúdo em miniatura, alegações de desempenho não suportadas ou instruções que não aparecem em nenhum lugar do corpo. O TOC nunca deve conter âncoras digitadas manualmente, destinos fora da página atual ou links para seções vazias.

Política de estabilidade de âncoras

Um ID de cabeçalho é a parte de fragmento de uma URL, como #politica-de-estabilidade-de-ancoras. Fragmentos de URL publicados são interfaces públicas. Bookmarks, links de campanhas, documentação de suporte, resultados de busca e respostas geradas por IA podem apontar diretamente para eles. Alterar o texto do cabeçalho pode alterar o ID gerado pelo Hugo e quebrar toda âncora de entrada, mesmo que a URL da página permaneça a mesma.

Após a publicação, congele os IDs de todos os cabeçalhos H2 e H3. Prefira editar o parágrafo abaixo de um cabeçalho em vez de renomear o cabeçalho. Quando uma renomeação for necessária, preserve o ID antigo usando um mecanismo de âncora explícita compatível com o sistema de publicação e verifique tanto o fragmento de entrada antigo quanto a nova seleção do TOC. Nunca reutilize um ID antigo para um assunto diferente, nunca duplique um ID na página e nunca traduza um ID em uma URL localizada existente sem um plano de migração. Registre alterações intencionais de âncora na nota de versão ou no registro de alterações de conteúdo para que os responsáveis por links de entrada conhecidos possam atualizá-los.

Tipos de postagem que o utilizam

O frontmatter postTypes lista os formatos para os quais este elemento faz parte do padrão de produção. Ainda é condicional: uma instância curta de um formato normalmente longo pode ficar abaixo do limite do TOC.

Páginas de produto, categoria e caso de uso não são incluídas por padrão porque suas jornadas principais são frequentemente tratadas por navegação no nível da página e chamadas para ação. Adicione este elemento apenas por meio de uma decisão documentada de template, não porque a página é longa por acaso.

Checklist de garantia de qualidade

• Confirme se a página atende ao limite: pelo menos 1.800 palavras, sete seções H2 ou uma necessidade documentada de navegação não linear.
• Confirme se a visão geral tem 40 a 90 palavras e declara escopo, resultado pretendido e qualquer exclusão necessária.
• Confirme se a visão geral não repete a resposta direta ou as principais conclusões.
• Confirme se o shortcode aparece uma vez, imediatamente após a visão geral e antes do primeiro H2.
• Confirme se cada H2 é um destino principal significativo e cada H3 é útil o suficiente para aparecer na navegação.
• Confirme se a lista gerada contém de 5 a 18 entradas, usa uma ordem lógica e não contém itens H4 sob a configuração atual.
• Confirme se config/_default/markup.toml ainda usa startLevel = 2, endLevel = 3 e ordered = false, ou atualize esta especificação com a alteração do componente.
• Confirme se uma página sem H2 elegível não alega conter um TOC; o shortcode renderizará silenciosamente nada.
• Confirme se todo fragmento gerado é único e alcança o cabeçalho pretendido.
• Teste URLs de âncora de entrada publicadas antes de alterar qualquer redação de H2 ou H3; preserve IDs antigos quando os cabeçalhos precisarem mudar.
• No desktop, verifique se o wrapper fixo está oculto a 300 pixels ou menos e aparece após a posição de rolagem exceder 300 pixels.
• Verifique se o wrapper fixo fica abaixo do cabeçalho real, a barra de progresso avança e o rótulo ativo acompanha as mudanças de seção.
• Verifique se viewports estreitas não mostram o controle atual e registre isso como comportamento atual esperado, não como uma captura de tela quebrada.
• Registre as limitações atuais de acessibilidade: nenhum landmark de navegação, nenhum gatilho visível focalizável por teclado, nenhuma transferência de foco, nenhuma atualização de fragmento e nenhum ramo de movimento reduzido.
• Confirme se nenhum caminho de captura de tela é renderizado até que o ativo correspondente exista em disco.

FAQ

As perguntas abaixo cobrem as decisões editoriais que mais frequentemente fazem com que este elemento seja adicionado cedo demais, tornado muito profundo ou quebrado após a publicação.