 |
Resumo | DiscoTOC permitirá que você gere uma tabela de conteúdos interativa 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 nos Temas do Discourse? | Guia para iniciantes sobre o uso de Temas do Discourse |
Instale este componente de tema
Exemplos
Desktop
Mobile
Recursos
toc = tabela de conteúdos
-
Gera automaticamente toda a toc por meio de um botão no menu de engrenagem do editor
-
A toc estará sempre na tela — rola junto com o conteúdo, como o widget de progresso do tópico
-
Conforme você rola para baixo e passa pelas seções do tópico, o elemento ativo na tabela de conteúdos será marcado como ativo (destaque azul)
-
adiciona atributos id aos títulos (você pode vincular a uma seção específica de outro tópico/postagem)
-
clicar em qualquer link na toc instruirá o navegador a navegar até a seção relevante (rolagem suave)
-
adiciona um link copiável ao lado de cada título (caso queira vincular a ele)
-
Suporte a RTL (leitura da direita para a esquerda)
-
As cores são baseadas na sua paleta de cores ativa atual
Como funciona?
Em resumo, ele procura por títulos nos tópicos que estão marcados para ter uma toc (por meio do botão do editor) e, se o tópico atual estiver marcado, ele pega todos os títulos e os coloca na toc (aninhados na ordem dos níveis de título) — isso significa que seu markdown deve estar sintaticamente correto.
# título 1
## título 2
### título 3
#### título 4
##### título 5
###### título 6
Você pode voltar e avançar nos níveis de título, mas a ordem deve estar correta
# título 2
## título 3
## título 3
### título 4
## título 3
# título 2
etc...
Para que os links na toc funcionem, os títulos devem ter atributos id. O componente verificará se os títulos já possuem ids e, se possuírem, eles serão respeitados. Isso é útil se você criou manualmente uma toc.
Se os títulos não tiverem ids, ele gerará um id para cada título com base em seu texto (caracteres indesejados são removidos)
Uma vez feito tudo isso, ele também adicionará um link ao lado de cada botão que leva diretamente àquela seção:
Configurações
| Nome | Descrição |
|---|---|
| nível mínimo de confiança para criar TOC | O nível mínimo de confiança que um usuário deve ter para ver o botão da TOC no editor |
| texto da toc no editor | Texto que aparece na parte superior do painel de pré-visualização do editor para indicar que o tópico terá uma tabela de conteúdos |
| categorias com TOC automática | Habilitar automaticamente a TOC em tópicos nestas categorias |
| tags com TOC automática | Habilitar automaticamente a TOC em tópicos com estas tags |
| TOC min título | Número mínimo de títulos em um tópico para que a tabela de conteúdos seja exibida |
Traduções
| Tradução | Padrão |
|---|---|
| table_of_contents | table of contents |
| insert_table_of_contents | Insert table of contents |
| jump_bottom | Jump to end |
| toggle_toc.show_timeline | Timeline |
| toggle_toc.show_toc | Contents |
O tema vem com três strings que você pode traduzir ou alterar.
table_of_contents: "table of contents"
isso é usado para o botão que abre a toc no mobile
insert_table_of_contents: "Insert table of contents"
isso é usado como o texto para o botão da toc no menu de engrenagem do editor
topic_will_contain_a_table_of_contents: "This topic will contain a table of contents"
Este é o texto que aparece na pré-visualização do editor para indicar que uma toc será gerada para o tópico
Como eu crio uma toc?
- Escreva um tópico com títulos sintaticamente corretos
- Clique no botão da toc no menu de engrenagem (aparece apenas ao criar um tópico regular — respostas e MPs são ignorados)
- Lucro.
O que acontece com o widget de progresso do tópico quando um tópico tem uma toc?
Como você provavelmente pode imaginar, não há espaço para mostrar ambos ao mesmo tempo, então a maneira como este componente funciona é a seguinte:
em um tópico com uma toc, o widget de progresso do tópico fica oculto enquanto a primeira postagem está na tela, e você vê a toc em vez disso.
Quando você rola para baixo e passa da primeira postagem, a toc não rola junto com você e o progresso do tópico é exibido em vez disso enquanto você lê as respostas.
Então, as primeiras postagens recebem a toc, e as postagens subsequentes recebem o widget de progresso regular do tópico.
Isso acontece tanto no desktop quanto no mobile.
Existem alguma desvantagem em usar este componente?
Nenhuma que eu saiba, todas as alterações são feitas no lado do cliente. Então você pode facilmente remover o componente e suas postagens voltarão ao estado anterior à instalação.
Limitações
Este componente assume o layout padrão de tópicos. Como tal, ele não funcionará com temas que modificam esse layout, como o tema Vincent. O suporte para temas populares que modificam o layout virá em uma etapa posterior na forma de configurações do componente.
Créditos
Eu comecei com a biblioteca tocify.js do Greg Franko. No entanto, parece que ela não foi atualizada há muito tempo, então esta é essencialmente uma bifurcação (fork) que remove muitos recursos desnecessários, integra e estiliza o restante para o Discourse.
Portanto, não há solicitações externas e o tamanho total é de ~ 4kb gzip.
Um grande obrigado ao @erlend_sh por muitos feedbacks valiosos e ao @david por sua ajuda com as traduções.
Hospedado por nós? Componentes de tema estão disponíveis para uso em nossos planos Pro, Business e Enterprise.
obrigado!
