 |
Riepilogo | Discourse Doc Categories offre la possibilità di riservare determinate categorie alla documentazione, abilitando funzionalità aggiuntive per esse. |
 |
Link al repository | https://github.com/discourse/discourse-doc-categories |
 |
Guida all’installazione | Come installare i plugin in Discourse |
Nota che questo plugin è in fase di sviluppo attivo e non è ancora completamente completo.
Funzionalità
Il plugin Discourse Doc Categories ti consente di ospitare documentazione strutturata su un forum Discourse esistente. Funziona riservando categorie specifiche alla documentazione e fornendo funzionalità per rendere più facile trovare argomenti di documentazione specifici.
Puoi vederlo in azione nella categoria Documentation.
Quando si contrassegna una categoria come luogo per la documentazione, vengono abilitate le seguenti funzionalità per quella categoria:
- Un argomento specificato da utilizzare come indice per tutti gli argomenti di documentazione nella categoria
- Una nuova barra laterale per navigare tra i diversi argomenti della categoria, incluse funzioni di filtraggio e ricerca integrate
- Nuovi report per aiutarti a mantenere l’integrità degli argomenti indice
Inoltre, il plugin gestisce i reindirizzamenti per i siti che migrano dal plugin Docs ritirato. I link alla documentazione di quel plugin verranno reindirizzati ai loro URL degli argomenti esistenti, ed è disponibile un’impostazione per reindirizzare la tua vecchia homepage della documentazione alla tua categoria principale di documentazione.
Configurazione
Le impostazioni di configurazione sono disponibili all’indirizzo example.discourse.com/admin/site_settings/category/doc_categories. Qui troverai le seguenti impostazioni:
doc categories enabled: Seleziona per abilitare il plugin Doc Categories.doc categories docs legacy enabled: Seleziona questa opzione se hai migrato dal plugin Docs deprecato.doc categories homepage: Con l’impostazione precedente abilitata, la pagina di atterraggio dal plugin Docs deprecato verrà reindirizzata a questo URL.
Per specificare quali categorie verranno utilizzate per la documentazione, assegnagli un argomento indice. Per fare ciò, apri le impostazioni della categoria facendo clic sull’icona 
nella pagina della categoria. Da lì, fai clic sul link ‘Impostazioni’ e scorri fino alla sezione ‘Modalità documentazione’. Usa il campo ‘Argomento indice’ per specificare l’argomento che verrà utilizzato per l’indice della categoria.
Argomenti indice
Gli argomenti indice per una categoria di documentazione servono a due scopi:
- Sono un elenco centrale di tutti gli argomenti inclusi nella categoria
- La barra laterale inclusa con questo plugin è popolata dal contenuto dell’argomento indice
Formattazione degli argomenti indice
Gli argomenti indice possono includere qualsiasi contenuto desideri. Affinché la barra laterale funzioni correttamente, devono includere un elenco puntato (o più elenchi puntati) di argomenti di documentazione. Questi possono essere semplicemente gli URL degli argomenti in un elenco, nel qual caso la barra laterale mostrerà il titolo completo per ciascun argomento di documentazione.
Avere il titolo completo nella barra laterale potrebbe non essere pratico se i tuoi titoli sono più lunghi di poche parole, quindi per impostare titoli più brevi per un determinato argomento, precedi l’URL con un titolo abbreviato seguito da due punti (:). Tutto il testo prima dei due punti verrà mostrato nella barra laterale e rimanderà all’URL dell’argomento.
Puoi dividere il tuo argomento indice in sezioni e utilizzare più elenchi con intestazioni (di qualsiasi livello) sopra ciascuna di esse: verranno quindi visualizzati nella barra laterale in queste sezioni.
Ecco un esempio di argomento indice per iniziare:
Puoi iniziare con una breve descrizione opzionale della categoria.
## Prima sezione
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Titolo breve: https://discourse.example.com/t/topic-with-a-long-title/56
* Altro titolo: https://discourse.example.com/t/another-topic-with-a-long-title/78
## Seconda sezione
* Titolo argomento: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
Questo esempio produrrà una barra laterale della documentazione che appare così:
Vedi l’argomento indice Documentation > Site Management per un esempio di un indice di categoria di documentazione in azione: https://meta.discourse.org/t/site-management-index/308032
Mantenimento degli argomenti indice
Mentre gli argomenti indice non verranno aggiornati automaticamente quando i contenuti nella categoria vengono aggiunti, rimossi o modificati, il plugin include nuovi report che evidenziano le inconsistenze all’interno degli argomenti indice.
-
Argomenti non indicizzati:
example.discourse.com/admin/reports/doc_categories_missing_topics
Questo report mostra tutti gli argomenti nelle categorie di documentazione che non sono stati aggiunti all’indice. -
Elementi estranei:
example.discourse.com/admin/reports/doc_categories_extraneous_items
Questo report mostra gli elementi inclusi nell’indice che sembrano non doverci essere. Il report indicherà il motivo per cui l’argomento è stato incluso nel report - ad esempio, se è stato eliminato o se si trova in una categoria diversa dall’argomento indice in cui è incluso.
Informazioni aggiuntive
Aggiungendo la stringa in:docs a un termine di ricerca, si cercherà in tutte le categorie contrassegnate per la documentazione (cioè che hanno un argomento indice assegnato).
Il numero massimo di elementi nell’indice è impostato dall’impostazione del sito Max oneboxes per post, che ha un valore predefinito di 50. Se hai bisogno di più di 50 elementi nell’indice, aumenta il numero in quell’impostazione.
)
Stavo esplorando la possibilità di spostare la mia documentazione su 
