Table of Contents Plus

Table of Contents Plus é um plugin WordPress poderoso, porém fácil de usar, que cria automaticamente um índice ou sumário (TOC) específico para o contexto de páginas longas (e tipos de postagem personalizados). Mais do que apenas um plugin de sumário, este plugin também pode gerar um sitemap listando páginas e/ou categorias em todo o seu site.

Descrição

Construído do zero e com a Wikipedia em mente, o sumário, por padrão, aparece antes do primeiro título em uma página. Isso permite que o autor insira conteúdo introdutório que pode resumir ou apresentar o restante da página. Ele também usa um esquema de numeração exclusivo que não se perde devido a diferenças de CSS entre os temas.

Este plugin é um ótimo complemento para sites ricos em conteúdo, como configurações orientadas a sistemas de gerenciamento de conteúdo. Dito isso, os blogueiros também têm os mesmos benefícios ao escrever artigos longos e estruturados.

O ToC Plus inclui um painel de opções de administração onde você pode personalizar configurações como posição de exibição, definir o número mínimo de títulos antes que um índice seja exibido, outra aparência e muito mais. Para usuários avançados, expanda as opções avançadas para ajustar ainda mais seu comportamento, incluindo:

• Exclua níveis de cabeçalho indesejados, como h5 e h6, de serem incluídos;
• Desative a saída do arquivo CSS incluído;
• Ajuste o deslocamento superior e mais.

Usando shortcodes, você pode substituir o comportamento padrão, como exclusões especiais em uma página específica ou até mesmo ocultar o índice de conteúdo completamente.

Prefere incluir o índice na barra lateral? Vá para Aparência > Widgets e arraste o TOC+ para a barra lateral e posição desejadas.

Tipos de postagem personalizados são suportados, no entanto, a inserção automática funciona apenas quando the_content() foi usado pelo tipo de postagem personalizado. Cada tipo de postagem aparecerá no painel de opções, então ative os que você deseja.

Capturas de tela

Instalar / Atualizar

Instale o plugin pesquisando por Table of Contents Plus na tela Adicionar Plugin, ou diretamente do repositório de plugins do WordPress.

Não há instruções especiais de atualização. Substitua sua pasta existente pela mais recente ou use a abordagem simplificada no menu do plugin. Suas opções não serão perdidas.

Ajuda

A abordagem mais simples

Para os impacientes, tudo o que você precisa fazer é ativar o plugin.

O plugin aplicará as configurações padrão e produzirá o índice de conteúdo antes do primeiro cabeçalho em páginas (não posts, nem tipos de postagem personalizados) com quatro ou mais cabeçalhos.

Nenhum shortcode é necessário.

Onde está meu índice de conteúdo?

1. Na maioria dos casos, o post, a página ou o tipo de postagem personalizado tem menos do que o número mínimo de cabeçalhos. Por padrão, este valor é definido como quatro, então certifique-se de ter pelo menos quatro cabeçalhos em seu conteúdo. Se você quiser alterar esse valor, pode encontrá-lo em 'Opções Principais' > 'Mostrar quando'.
2. A inserção automática está habilitada para o seu tipo de conteúdo? Por padrão, apenas páginas estão habilitadas.
3. Você tem [no_toc] em algum lugar no conteúdo? Isso desabilitará o índice para o post, página ou tipo de postagem personalizado atual.
4. Se você estiver usando o widget TOC+, verifique se você tem a opção "Mostrar o índice de conteúdo apenas na barra lateral" habilitada, pois isso limitará sua exibição apenas à barra lateral. Você pode verificar isso indo em Aparência > Widgets.
5. Você pode ter restringido a geração a uma correspondência de caminho de URL. A configuração pode ser encontrada na seção avançada em Opções Principais.

Como faço para parar o índice de conteúdo de aparecer em uma única página?

Coloque o seguinte [no_toc] em qualquer lugar da página para suprimir o índice de conteúdo. Isso é conhecido como um shortcode e funciona para posts, páginas e tipos de postagem personalizados que utilizam the_content()

Defini o encapsulamento para esquerda ou direita, mas os cabeçalhos não envolvem o índice de conteúdo

Isso normalmente ocorre quando há uma diretiva CSS clear no cabeçalho ou ao redor dele, originada do tema (Twenty Eleven e Twenty Twelve são dois temas que fazem isso). Essa diretiva informa ao agente do usuário para redefinir as especificações de encapsulamento anteriores.

Você pode ajustar o CSS do seu tema ou tentar mover a posição do índice de conteúdo para o topo da página.

Tente adicionar o seguinte CSS para permitir que a quebra ocorra ao redor do sumário:

h1, h2, h3, h4, h5, h6 { clear: none; }

Como incluo o nome da página no título do sumário?

Como o título da página muda dependendo da página que você está visualizando, você pode usar a seguinte variável especial para inserir automaticamente o título da página no cabeçalho do sumário:

%PAGE_NAME%

Você pode usá-la como está ou colocar texto em ambos os lados da variável.

Como exemplo: se sua página se chama Grandes Esperanças e o título do seu sumário está definido como Conteúdo para %PAGE_NAME%, o título final seria Conteúdo para Grandes Esperanças

Meu site tem 100 páginas, mas só quero que o sumário apareça em 10 delas

Você poderia colocar [no_toc] nas 90 páginas, mas isso não seria divertido... então tente o seguinte:

1. Vá para Configurações > TOC+ e desative a opção de inserção automática para páginas (ou o tipo de conteúdo com o qual você está trabalhando).
2. Adicione [toc] nas 10 páginas que precisam delas. Note que o sumário aparecerá onde você colocou o shortcode.

Alternativamente, você também pode experimentar a opção de restringir caminho se as páginas nas quais você deseja incluir o índice estiverem todas dentro de uma determinada seção do seu site (por exemplo, /doc/).

Quero ignorar certos cabeçalhos

Use a opção 'excluir cabeçalhos' se você quiser ignorar certos cabeçalhos. Separe vários cabeçalhos com uma barra vertical |. Use um asterisco * como curinga para corresponder a outros textos. Note que isso não diferencia maiúsculas de minúsculas. Alguns exemplos incluem:

• Fruit* ignora cabeçalhos que começam com Fruit
• *Fruit Diet* ignora cabeçalhos com Fruit Diet em algum lugar no cabeçalho
• Apple Tree|Oranges|Yellow Bananas ignora cabeçalhos que são exatamente Apple Tree, Oranges ou Yellow Bananas

Posso ter o sumário na barra lateral?

Use o widget TOC+ e arraste-o para a posição desejada. Se você quiser que o sumário seja exibido apenas na barra lateral, certifique-se de marcar essa opção no widget.

Ao contrário da Wikipédia, quero que todas as minhas âncoras sejam minúsculas e usem hifens em vez de underscores

Existem duas opções que permitem ajustar a capitalização e o uso de hifens. Se você ainda precisar de mais, pode ajustá-lo um pouco mais anexando ao filtro toc_url_anchor_target. Veja a seção desenvolvedores abaixo para um exemplo.

Gostaria de incorporar um sitemap

1. Crie uma página para o seu sitemap (se você já tiver uma, use-a em vez disso).
2. Adicione [sitemap] à sua página e salve.

O exemplo acima é o mais simples de integrar um sitemap listando todas as páginas e categorias. Você pode personalizar as opções do sitemap em Configurações > TOC+ ou conferir alguns dos usos mais avançados com os shortcodes relacionados a sitemap abaixo.

Você também pode incorporar um sitemap usando um widget de texto e colando qualquer um dos shortcodes de sitemap.

O sitemap usa uma fonte estranha, diferente do resto do site

Nenhum estilo extra é criado para o sitemap, em vez disso, ele herda quaisquer estilos que você usou ao adicionar o shortcode. Se você copiou e colou, provavelmente também copiou as tags de ‘código’ que o cercam, então remova-as se for esse o caso.

Na maioria dos casos, tente ter o shortcode em sua própria linha, sem nada antes ou depois dos colchetes.

Shortcodes

O plugin foi projetado para ser o mais integrado e indolor possível e não exigiu que você inserisse um shortcode para operar. No entanto, usar o shortcode permite controlar totalmente a posição do sumário em sua página. Os seguintes shortcodes estão disponíveis com este plugin.

Quando os parâmetros são omitidos para os shortcodes abaixo, eles voltarão às configurações que você definiu em Configurações > TOC+.

[toc]

Permite gerar o sumário na posição preferida. Também é útil para sites que exigem um TOC apenas em um pequeno número de páginas.

Atributos:

• label: texto, título do sumário
• no_label: true/false, exibe ou oculta o título
• wrapping: texto, "left" ou "right"
• heading_levels: números, isso permite selecionar os níveis de título que você deseja incluir no sumário. Separe vários níveis com uma vírgula. Exemplo: inclua os títulos 3, 4 e 5, mas exclua os outros com heading_levels="3,4,5"
• exclude: texto, insira os títulos a serem excluídos. Separe vários títulos com um pipe |. Use um asterisco * como curinga para corresponder a outros textos. Você também pode usar expressões regulares para correspondências mais avançadas.
• class: texto, insira classes CSS a serem adicionadas ao contêiner. Separe várias classes com um espaço.

[no_toc]

Permite desativar o sumário para a postagem, página ou tipo de postagem personalizado atual.

[sitemap]

Produz uma listagem de todas as páginas e categorias do seu site. Você pode usá-lo em qualquer postagem, página ou até mesmo em um widget de texto.

[sitemap_pages]

Permite imprimir uma listagem apenas de páginas.

Atributos:

• heading: número entre 1 e 6, define qual título html usar
• label: texto, título da lista
• no_label: true/false, exibe ou oculta o título da lista
• exclude: IDs das páginas ou categorias que você deseja excluir
• exclude_tree: ID da página ou categoria que você deseja excluir, incluindo todos os seus descendentes

[sitemap_categories]

Semelhante a [sitemap_pages] mas para categorias.

[sitemap_posts]

Isso permite que você imprima um índice de todas as postagens publicadas em seu site. Por padrão, as postagens são listadas em ordem alfabética, agrupadas por suas primeiras letras. Existem classes CSS para cada seção, letra e lista, permitindo que você personalize a aparência.

Atributos:

• order: texto, ASC ou DESC
• orderby: texto, opções populares incluem “title”, “date”, “ID” e “rand”. Veja WP_Query para uma lista.
• separate: true/false (padrão é true), não separa as listas por primeira letra quando definido como false.

Para desenvolvedores

Como personalizo minhas âncoras?

Se você ainda não estiver satisfeito com as âncoras, pode modificá-las para atender às suas necessidades por meio de uma função personalizada conectada ao filtro toc_url_anchor_target. Como exemplo, coloque o trecho de código abaixo em seu arquivo functions.php para converter todas as âncoras em maiúsculas.

function my_custom_anchor( $anchor ) {
	return strtoupper( $anchor );
}
add_filter( 'toc_url_anchor_target', 'my_custom_anchor' );

toc_get_index( $content = ”, $prefix_url = ” )

Retorna uma string formatada em HTML do índice sem as tags UL ou OL circundantes para permitir que o editor do tema forneça seus próprios ID e/ou classes para a lista externa.

Ambos os parâmetros são opcionais:

• $content é o conteúdo inteiro com os títulos. Se estiver em branco, usará o conteúdo atual encontrado em $post (por exemplo, dentro do “loop”).
• $prefix_url é o URL a ser prefixado à âncora. Se uma string foi fornecida, ela será usada como está. Se definido como true, tentará obter o permalink do objeto $post.

Estes exemplos assumem que você está dentro do “loop”:

1. Obtenha o índice da página atual:

echo '<ul id="my_toc">' . toc_get_index() . '</ul>';

2. Crie uma lista de todos os filhos e seus títulos:

$children = new WP_Query(array(
  'post_parent' => get_the_ID(),
  'posts_per_page' => -1	// get all children
));
while ( $children->have_posts() ) {
  $children->the_post();
  echo 
 '<h3>' . get_the_title() . '</h3>' .
 '<ul>' . toc_get_index( get_the_content(), get_permalink( $children->post->ID ) ) . '</ul>'
  ;
}
wp_reset_postdata();