 |
Resumo | DiscoTOC permitirá que você gere um índice interativo para seus tópicos com um clique! |
 |
Pré-visualização | Pré-visualização no Discourse Theme Creator |
 |
Link do Repositório | https://github.com/discourse/DiscoTOC |
 |
Novo em Temas do Discourse? | Guia para iniciantes sobre o uso de Temas do Discourse |
Instale este componente de tema
Amostras
Desktop
Mobile
Recursos
toc = table of contents (índice)
-
Gera automaticamente todo o índice por meio de um botão no menu de configurações do editor
-
O índice estará sempre na tela – rola junto com o conteúdo, como o widget de progresso do tópico
-
Conforme você rola passando pelas seções do tópico, o elemento ativo no índice será destacado (realce azul)
-
Cada entrada do índice linka para a âncora do cabeçalho, então você também pode linkar para uma seção específica de outro tópico ou postagem
-
Clicar em qualquer link do índice instruirá o navegador a navegar para a seção relevante (rolagem suave)
-
Em tópicos com respostas, um botão Índice / Cronologia permite aos leitores alternar entre o índice e a cronologia normal do tópico. A escolha é lembrada no navegador
-
Funciona com o plugin Discourse Docs
-
Suporte opcional para índices em respostas, não apenas na primeira postagem
-
Suporte para RTL (direita para esquerda)
Como funciona?
Em resumo, ele procura por cabeçalhos em tópicos que estão marcados para ter um índice (por meio do botão do editor) e, se o tópico atual estiver marcado, ele pega todos os cabeçalhos e os coloca no índice (aninhados na ordem dos níveis de cabeçalho) – isso significa que seu markdown deve estar sintaticamente correto.
# cabeçalho 1
## cabeçalho 2
### cabeçalho 3
#### cabeçalho 4
##### cabeçalho 5
Você pode alternar livremente entre os níveis de cabeçalho, mas a ordem deve estar correta
# cabeçalho 2
## cabeçalho 3
## cabeçalho 3
### cabeçalho 4
## cabeçalho 3
# cabeçalho 2
etc...
Algumas coisas importantes sobre quais cabeçalhos são compatíveis
h1ah5são incluídos.h6não é- Cabeçalhos dentro de citações são ignorados, então citações não poluirão o índice
- O índice só aparece se a postagem tiver pelo menos tantos cabeçalhos quanto a configuração Mínimo de cabeçalhos para índice (3 por padrão)
Como funcionam os links no índice?
Cada cabeçalho em uma postagem processada recebe uma âncora no formato p-<id da postagem>-<slug do cabeçalho>-<número> — é o destino por trás de um cabeçalho. O DiscoTOC linka para essas âncoras em vez de criar as suas próprias.
Como essas âncoras incluem a posição do cabeçalho na postagem, elas mudam se você reordenar ou renomear os cabeçalhos. Se você estiver linkando para seções de outros lugares, pode adicionar âncoras nomeadas estáveis acima do cabeçalho:
<div><a name="minha-secao"></a></div>
## Minha seção
Então link para /t/seu-slug-de-topico/1234#minha-secao. O Discourse permite <a name="..."> em postagens. As próprias entradas do DiscoTOC continuarão usando as âncoras de cabeçalho do núcleo, mas as suas continuarão funcionando independentemente de edições.
Configurações
| Nome | Descrição |
|---|---|
| nível mínimo de confiança para criar índice | O usuário deve ter isso para ver o botão de índice no editor |
| texto do índice no editor | Texto que aparece no editor para indicar que o tópico terá um índice |
| categorias de índice automático | Habilita automaticamente categorias |
| tags de índice automático | Habilita automaticamente índice em tópicos com essas tags |
| habilitar índice para respostas | Permite índice em respostas. Índices em respostas não são afetados pelas configurações de tags de índice automático e categorias de índice automático e devem ser inseridos manualmente |
| mínimo de cabeçalhos para índice | Número mínimo de cabeçalhos em um tópico para que o índice seja exibido |
texto do índice no editor é o que aparece na pré-visualização do editor para indicar que um índice será gerado:
Traduções
| Tradução | Padrão |
|---|---|
| table_of_contents | índice |
| insert_table_of_contents | Inserir índice |
| jump_bottom | Ir para o final |
| toggle_toc.show_timeline | Cronologia |
| toggle_toc.show_toc | Índice |
table_of_contents: "índice"
isso é usado para o botão que abre o índice no mobile
insert_table_of_contents: "Inserir índice"
isso é usado como o texto do botão de índice no menu de configurações do editor
toggle_toc.show_toc: "Índice"
toggle_toc.show_timeline: "Cronologia"
esses rotulam o botão que alterna entre o índice e a cronologia do tópico
Como crio um índice?
- Escreva um tópico com cabeçalhos sintaticamente corretos
- Clique no botão de índice no menu de configurações do editor. Por padrão, ele só aparece na primeira postagem de um tópico; habilite a configuração habilitar índice para respostas para usá-lo em respostas também
- Lucro.
O que acontece com o widget de progresso do tópico quando um tópico tem um índice?
Não há espaço para mostrar ambos ao mesmo tempo, então em um tópico com índice, o widget de progresso do tópico é ocultado enquanto você está na primeira postagem, e você vê o índice em vez disso. Assim que você rola passando a primeira postagem, o índice é substituído pelo widget de progresso do tópico regular enquanto você lê as respostas. (Com habilitar índice para respostas ativado, uma resposta que tem seu próprio índice mostra aquele em vez disso.)
Em tópicos com mais de uma postagem, um botão Índice / Cronologia permite aos leitores alternar entre os dois, e a preferência é lembrada em seu navegador.
Em telas estreitas, o índice abre como uma sobreposição por meio de um botão na área de progresso do tópico.
Há alguma desvantagem em usar este componente?
Quase tudo acontece no lado do cliente, então você pode remover o componente a qualquer momento e suas postagens serão renderizadas como eram antes. A única coisa que afeta seu conteúdo é o botão do editor: ele envolve a postagem em um marcador <div data-theme-toc="true">, que é como o componente sabe que a postagem deve ter um índice. Se você desinstalar o componente, esse wrapper permanece na postagem, mas não tem efeito visível.
Limitações
Cabeçalhos h6 e cabeçalhos dentro de citações não são incluídos no índice.
Créditos
Isso começou como um hard fork da biblioteca tocify.js do Greg Franko, e desde então foi reescrito como componentes Ember nativos. Não há dependências externas ou solicitações.
Muito obrigado ao @erlend_sh por muitas valiosas sugestões e ao @david por sua ajuda com traduções.