|||
-|-|-|
| Resumo | Categorias de Documentos do Discourse oferece a capacidade de reservar categorias específicas para documentação, habilitando recursos adicionais para elas.
| Link do Repositório | https://github.com/discourse/discourse-doc-categories
| Guia de Instalação | Como instalar plugins no Discourse
Observe que este plugin está em desenvolvimento ativo e ainda não está totalmente completo.
Recursos
O plugin Discourse Doc Categories permite que você hospede documentação estruturada em um fórum Discourse existente. Ele funciona reservando categorias específicas para documentação e fornecendo recursos para facilitar a localização de tópicos de documentação específicos.
Você pode vê-lo em ação na categoria Documentation.
Ao marcar uma categoria como um local para documentação, os seguintes recursos são habilitados para essa categoria:
- Um tópico especificado para ser usado como índice para todos os tópicos de documentação na categoria
- Uma nova barra lateral para navegar entre diferentes tópicos na categoria, incluindo funções integradas de filtragem e pesquisa
- Novos relatórios para ajudar a manter a integridade dos tópicos do índice
Além disso, o plugin lida com redirecionamentos para sites que estão migrando do plugin Docs desativado. Os links de documentação desse plugin redirecionarão para seus URLs de tópico existentes, e há uma configuração para redirecionar sua página inicial de documentação anterior para sua categoria de documentação principal.
Configuração
As configurações de configuração estão disponíveis em exemplo.discourse.com/admin/site_settings/category/doc_categories. Aqui você encontrará as seguintes configurações:
doc categories enabled: Selecione para habilitar o plugin Doc Categories.doc categories docs legacy enabled: Selecione isso se você migrou do plugin Docs desativado.doc categories homepage: Com a configuração anterior habilitada, a página de destino do plugin Docs desativado redirecionará para este URL.
Para especificar quais categorias serão usadas para documentação, atribua a elas um tópico de índice. Para fazer isso, abra as configurações da categoria clicando no ícone 
na página da categoria. A partir daí, clique no link ‘Configurações’ e role para baixo até a seção ‘Modo de documentação’. Use o campo ‘Tópico de índice’ para especificar o tópico que será usado para o índice da categoria.
Tópicos de índice
Os tópicos de índice para uma categoria de documentação servem a dois propósitos:
- Eles são uma lista central de todos os tópicos incluídos na categoria
- A barra lateral incluída com este plugin é preenchida com o conteúdo do tópico de índice
Formatação de tópicos de índice
Os tópicos de índice podem incluir qualquer conteúdo que você desejar. Para que a barra lateral funcione corretamente, eles precisam incluir uma lista com marcadores (ou várias listas com marcadores) de tópicos de documentação. Estes podem ser simplesmente os URLs dos tópicos em uma lista, caso em que a barra lateral mostrará o título completo para cada tópico de documentação.
Ter o título completo na barra lateral pode não ser prático se seus títulos forem mais longos do que algumas palavras, portanto, para definir títulos mais curtos para um tópico específico, preceda o URL com um título abreviado seguido por dois pontos (:). Todo o texto antes dos dois pontos será exibido na barra lateral e vinculará ao URL do tópico.
Você pode dividir seu tópico de índice em seções e usar várias listas com cabeçalhos (de qualquer nível) acima de cada uma - elas serão exibidas na barra lateral nessas seções.
Aqui está um exemplo de tópico de índice para você começar:
Você pode começar com uma descrição opcional breve da categoria.
## Primeira seção
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Título curto: https://discourse.example.com/t/topic-with-a-long-title/56
* Outro título: https://discourse.example.com/t/another-topic-with-a-long-title/78
## Segunda seção
* Título do tópico: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
Esse exemplo produzirá uma barra lateral de documentação que se parece com isto:
Veja o tópico de índice Documentation > Site Management para um exemplo de índice de categoria de documentação em ação: https://meta.discourse.org/t/site-management-index/308032
Manutenção de tópicos de índice
Embora os tópicos de índice não sejam atualizados automaticamente à medida que o conteúdo na categoria é adicionado, removido ou editado, o plugin inclui novos relatórios que destacam onde há inconsistências nos tópicos de índice.
-
Tópicos não indexados:
exemplo.discourse.com/admin/reports/doc_categories_missing_topics
Este relatório mostra quaisquer tópicos nas categorias de documentação que não foram adicionados ao índice. -
Itens extranhos:
exemplo.discourse.com/admin/reports/doc_categories_extraneous_items
Este relatório mostra itens incluídos no índice que parecem não dever estar lá. O relatório indicará o motivo pelo qual o tópico foi incluído no relatório - por exemplo, se foi excluído ou se está em uma categoria diferente daquela em que está incluído.
Informações adicionais
Adicionar a string in:docs a um termo de pesquisa pesquisará todas as categorias marcadas para documentação (ou seja, elas têm um tópico de índice atribuído).
O número máximo de itens no índice é definido pela configuração do site Max oneboxes per post, que tem o valor padrão de 50. Se você precisar de mais de 50 itens de índice, aumente o número nessa configuração.
)
Eu estava explorando a migração da minha documentação para o 
