||||
-|-|
| Resumo | Discourse Doc Categories permite que categorias específicas sejam reservadas 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 busca por tópicos de documentação específicos.
Você pode ver isso em ação na categoria Documentation.
Ao marcar uma categoria como 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 os diferentes tópicos da categoria, incluindo funções de filtragem e pesquisa integradas
- Novos relatórios para ajudar a manter a integridade dos tópicos de índice
Além disso, o plugin lida com redirecionamentos para sites que estão migrando do plugin Docs aposentado. Os links de documentação desse plugin serão redirecionados para suas URLs de tópico existentes, e há uma configuração para redirecionar sua página inicial de documentação anterior para sua categoria principal de documentação.
Configuração
As configurações de configuração estão disponíveis em example.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 descontinuado.doc categories homepage: Com a configuração anterior habilitada, a página inicial do plugin Docs descontinuado será redirecionada para esta 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 de uma categoria de documentação servem para 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 pelo 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 múltiplas listas com marcadores) de tópicos de documentação. Essas podem ser simplesmente as URLs dos tópicos em uma lista, caso em que a barra lateral mostrará o título completo de cada tópico de documentação.
Ter o título completo na barra lateral pode não ser prático se seus títulos tiverem mais do que algumas palavras, então, para definir títulos mais curtos para um tópico específico, preceda a URL com um título encurtado seguido por dois pontos (:). Todo o texto antes dos dois pontos será exibido na barra lateral e ele vinculará à 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 então exibidas na barra lateral nessas seções.
Aqui está um exemplo de um tópico de índice para começar:
Você pode começar com uma breve descrição opcional 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 um índice de categoria de documentação em ação: https://meta.discourse.org/t/site-management-index/308032
Mantendo tópicos de índice
Enquanto os tópicos de índice não serão atualizados automaticamente conforme 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:
example.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 excessivos:
example.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á a razão pela qual o tópico foi incluído no relatório - por exemplo, se foi excluído ou se está em uma categoria diferente do tópico de índice 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 é definida como 50 por padrão. 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 
