 |
Resumen | Discourse Doc Categories proporciona la capacidad de reservar categorías específicas para documentación, habilitando características adicionales para ellas. |
 |
Enlace al repositorio | https://github.com/discourse/discourse-doc-categories |
 |
Guía de instalación | Cómo instalar plugins en Discourse |
Ten en cuenta que este plugin está en desarrollo activo y aún no está completamente completo.
Características
El plugin Discourse Doc Categories te permite alojar documentación estructurada en un foro de Discourse existente. Funciona reservando categorías específicas para documentación y proporcionando características para facilitar la búsqueda de temas de documentación específicos.
Puedes verlo en acción en la categoría #documentación.
Al marcar una categoría como ubicación para documentación, se habilitan las siguientes características para esa categoría:
- Un tema específico que se utilizará como índice para todos los temas de documentación en la categoría
- Una nueva barra lateral para navegar entre diferentes temas en la categoría, incluidas funciones de filtrado y búsqueda integradas
- Nuevos informes para ayudarte a mantener la integridad de los temas del índice
Además, el plugin maneja redirecciones para sitios que migran desde el plugin Docs retirado. Los enlaces de documentación de ese plugin se redirigirán a sus URL de tema existentes, y hay una configuración para redirigir tu página de inicio de documentación anterior a tu categoría principal de documentación.
Configuración
La configuración está disponible en example.discourse.com/admin/site_settings/category/doc_categories. Aquí encontrarás las siguientes configuraciones:
doc categories enabled: Selecciona para habilitar el plugin Doc Categories.doc categories docs legacy enabled: Selecciona esto si has migrado desde el plugin Docs obsoleto.doc categories homepage: Con la configuración anterior habilitada, la página de destino del plugin Docs obsoleto se redirigirá a esta URL.
Para especificar qué categorías se utilizarán para documentación, asígnales un tema índice. Para hacerlo, abre la configuración de la categoría haciendo clic en el icono :llave_inglesa: en la página de la categoría. Desde allí, haz clic en el enlace ‘Configuración’ y desplázate hasta la sección ‘Modo de documentación’. Usa el campo ‘Tema índice’ para especificar el tema que se utilizará como índice de la categoría.
Temas índice
Los temas índice de una categoría de documentación cumplen dos propósitos:
- Son una lista central de todos los temas incluidos en la categoría
- La barra lateral incluida con este plugin se llena con el contenido del tema índice
Formatear temas índice
Los temas índice pueden incluir cualquier contenido que desees. Para que la barra lateral funcione correctamente, deben incluir una lista con viñetas (o múltiples listas con viñetas) de temas de documentación. Estas pueden ser simplemente las URL de los temas en una lista, en cuyo caso la barra lateral mostrará el título completo de cada tema de documentación.
Tener el título completo en la barra lateral podría no ser práctico si tus títulos son más largos que unas pocas palabras, por lo que para establecer títulos más cortos para un tema en particular, precede la URL con un título abreviado seguido de dos puntos (:). Todo el texto antes de los dos puntos se mostrará en la barra lateral y enlazará a la URL del tema.
Puedes dividir tu tema índice en secciones y usar múltiples listas con encabezados (de cualquier nivel) encima de cada una; entonces se mostrarán en la barra lateral en estas secciones.
Aquí tienes un ejemplo de un tema índice para comenzar:
Puedes comenzar con una breve descripción opcional de la categoría.
## Primera sección
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Título corto: https://discourse.example.com/t/topic-with-a-long-title/56
* Otro título: https://discourse.example.com/t/another-topic-with-a-long-title/78
## Segunda sección
* Título del tema: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
Ese ejemplo producirá una barra lateral de documentación que se verá así:
Consulta el tema índice de #documentación:site-management para ver un ejemplo de un índice de categoría de documentación en acción: https://meta.discourse.org/t/site-management-index/308032
Mantenimiento de temas índice
Aunque los temas índice no se actualizarán automáticamente a medida que se agregue, elimine o edite contenido en la categoría, el plugin incluye nuevos informes que destacan dónde hay inconsistencias dentro de los temas índice.
-
Temas no indexados:
example.discourse.com/admin/reports/doc_categories_missing_topics
Este informe muestra cualquier tema en las categorías de documentación que no se haya agregado al índice. -
Elementos extraños:
example.discourse.com/admin/reports/doc_categories_extraneous_items
Este informe muestra elementos incluidos en el índice que parecen no deber estar ahí. El informe indicará la razón por la que el tema ha sido incluido en el informe; por ejemplo, si ha sido eliminado o si está en una categoría diferente a la del tema índice en el que está incluido.
Información adicional
Agregar la cadena in:docs a un término de búsqueda buscará en todas las categorías marcadas para documentación (es decir, que tienen un tema índice asignado).
El número máximo de elementos en el índice está establecido por la configuración del sitio Max oneboxes per post, que por defecto es 50. Si necesitas más de 50 elementos de índice, aumenta el número en esa configuración.
)
Estaba explorando la posibilidad de mover mi documentación a 
