 |
Riepilogo | DiscoTOC ti permetterà di generare con un clic un indice interattivo per i tuoi argomenti! |
 |
Anteprima | Anteprima su Discourse Theme Creator |
 |
Link al repository | https://github.com/discourse/DiscoTOC |
 |
Prima volta con i temi di Discourse? | Guida per principianti all’uso dei temi di Discourse |
Installa questo componente del tema
Esempi
Desktop
Mobile
Funzionalità
toc = table of contents (indice)
-
Genera automaticamente l’intero indice tramite un pulsante nel menu a ingranaggio del compositore
-
L’indice rimarrà sempre visibile a schermo: scorre insieme al contenuto, come il widget di avanzamento dell’argomento
-
Mentre scorri oltre le sezioni dell’argomento, l’elemento attivo nell’indice verrà evidenziato (evidenziatura blu)
-
Ogni voce dell’indice linka all’ancora dell’intestazione, quindi puoi anche linkare a una sezione specifica da un altro argomento o post
-
Cliccando su qualsiasi link nell’indice, il browser navigerà verso la sezione rilevante (scroll fluido)
-
Negli argomenti con risposte, un pulsante Contenuti / Timeline permette ai lettori di passare tra l’indice e la timeline normale dell’argomento. La scelta viene memorizzata nel browser
-
Funziona con il plugin Discourse Docs
-
Supporto opzionale per indici nelle risposte, non solo nel primo post
-
Supporto RTL
Come funziona?
In sintesi, cerca le intestazioni negli argomenti contrassegnati per avere un indice (tramite il pulsante del compositore) e, se l’argomento corrente è contrassegnato, prende tutte le intestazioni e le inserisce nell’indice (annidate in ordine di livello di intestazione) - questo significa che il tuo markdown deve essere sintatticamente corretto.
# intestazione 1
## intestazione 2
### intestazione 3
#### intestazione 4
##### intestazione 5
Puoi tornare avanti e indietro tra i livelli di intestazione, ma l’ordine deve essere corretto
# intestazione 2
## intestazione 3
## intestazione 3
### intestazione 4
## intestazione 3
# intestazione 2
ecc...
Alcune cose da sapere sulle intestazioni compatibili
- Sono incluse da
h1ah5.h6non è incluso - Le intestazioni all’interno delle citazioni vengono ignorate, quindi le citazioni non inquinano l’indice
- L’indice appare solo se il post ha almeno tante intestazioni quante impostate nella configurazione minimo intestazioni indice (3 di default)
Come funzionano i link nell’indice?
Ogni intestazione in un post elaborato riceve un’ancora nella forma p-<id post>-<slug intestazione>-<numero> — è il target dietro un’intestazione. DiscoTOC linka a queste ancore invece di crearne di proprie.
Poiché queste ancore includono la posizione dell’intestazione nel post, cambiano se riordini o rinomini le intestazioni. Se stai linkando a sezioni da altri posti, puoi aggiungere ancore nominate stabili sopra l’intestazione:
<div><a name="mia-sezione"></a></div>
## La mia sezione
Poi linka a /t/il-tuo-slug-argomento/1234#mia-sezione. Discourse permette <a name="..."> nei post. Le voci proprie di DiscoTOC continueranno a usare le ancore delle intestazioni core, ma le tue continueranno a funzionare indipendentemente dalle modifiche.
Impostazioni
| Nome | Descrizione |
|---|---|
| livello di fiducia minimo per creare indice | Livello necessario per vedere il pulsante dell’indice nel compositore |
| testo indice compositore | Testo che appare in alto nel compositore per indicare che l’argomento avrà un indice |
| categorie indice automatico | Abilita automaticamente per le categorie |
| tag indice automatico | Abilita automaticamente l’indice negli argomenti con questi tag |
| abilita indice per le risposte | Permette l’indice nelle risposte. Gli indici delle risposte non sono influenzati dalle impostazioni tag indice automatico e categorie indice automatico e devono essere inseriti manualmente |
| minimo intestazioni indice | Numero minimo di intestazioni in un argomento perché l’indice venga mostrato |
testo indice compositore è ciò che appare nell’anteprima del compositore per indicare che verrà generato un indice:
Traduzioni
| Traduzione | Default |
|---|---|
| table_of_contents | indice |
| insert_table_of_contents | Inserisci indice |
| jump_bottom | Vai alla fine |
| toggle_toc.show_timeline | Timeline |
| toggle_toc.show_toc | Contenuti |
table_of_contents: "indice"
questo è usato per il pulsante che apre l’indice su mobile
insert_table_of_contents: "Inserisci indice"
questo è usato come testo per il pulsante dell’indice nel menu a ingranaggio del compositore
toggle_toc.show_toc: "Contenuti"
toggle_toc.show_timeline: "Timeline"
questi etichettano il pulsante che passa tra l’indice e la timeline dell’argomento
Come creo un indice?
- Scrivi un argomento con intestazioni sintatticamente corrette
- Clicca il pulsante dell’indice nel menu a ingranaggio del compositore. Di default appare solo nel primo post di un argomento; abilita l’impostazione abilita indice per le risposte per usarlo anche nelle risposte
- Profitto.
Cosa succede al widget di avanzamento dell’argomento quando un argomento ha un indice?
Non c’è spazio per mostrare entrambi contemporaneamente, quindi in un argomento con indice il widget di avanzamento dell’argomento è nascosto mentre sei sul primo post, e vedi l’indice invece. Una volta che scorri oltre il primo post, l’indice viene sostituito dal widget di avanzamento dell’argomento normale mentre leggi le risposte. (Con abilita indice per le risposte attivo, una risposta che ha il proprio indice mostra quello invece.)
Negli argomenti con più di un post, un pulsante Contenuti / Timeline permette ai lettori di passare tra i due, e la preferenza viene memorizzata nel loro browser.
Su schermi stretti l’indice si apre come overlay tramite un pulsante nell’area di avanzamento dell’argomento.
Ci sono lati negativi nell’usare questo componente?
Quasi tutto avviene lato client, quindi puoi rimuovere il componente in qualsiasi momento e i tuoi post verranno renderizzati come prima. L’unica cosa che tocca il tuo contenuto è il pulsante del compositore: avvolge il post in un marcatore <div data-theme-toc="true">, che è il modo in cui il componente sa che il post deve avere un indice. Se disinstalli il componente, quell’involucro rimane nel post ma non ha alcun effetto visibile.
Limitazioni
Le intestazioni h6 e le intestazioni all’interno delle citazioni non sono incluse nell’indice.
Crediti
Questo è iniziato come un hard fork della libreria tocify.js di Greg Franko, ed è stato successivamente riscritto come componenti Ember nativi. Non ci sono dipendenze esterne o richieste.
Un grande ringraziamento a @erlend_sh per il prezioso feedback e a @david per il suo aiuto con le traduzioni.
grazie!
