|||
-|-|-|
| Resumen | Discourse Doc Categories ofrece la capacidad de reservar categorías específicas para documentación, habilitando funcionalidades 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 terminado.
Funcionalidades
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 funcionalidades para facilitar la búsqueda de temas de documentación específicos.
Puedes verlo en acción en la categoría Documentation.
Al marcar una categoría como ubicación para documentación, se habilitan las siguientes funcionalidades para esa categoría:
- Un tema especificado para ser utilizado como índice de todos los temas de documentación de la categoría.
- Una nueva barra lateral para navegar entre diferentes temas de la categoría, incluyendo funciones integradas de filtrado y búsqueda.
- Nuevos reportes para ayudarte a mantener la integridad de los temas índice.
Además, el plugin maneja redirecciones para sitios que migran desde el plugin Docs retirado. Los enlaces de documentación de ese plugin redirigirán a sus URLs de tema existentes, y hay una configuración para redirigir tu página de inicio de documentación anterior a tu categoría de documentación principal.
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 redirigirá a esta URL.
Para especificar qué categorías se utilizarán para la documentación, asígnales un tema índice. Para hacer esto, abre la configuración de la categoría haciendo clic en el icono 
en la página de la categoría. Desde allí, haz clic en el enlace ‘Settings’ y desplázate hacia abajo hasta la sección ‘Documentation mode’. Utiliza el campo ‘Index topic’ 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 popula con el contenido del tema índice.
Formateo de 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. Estos pueden ser simplemente las URLs 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 acortado 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; estas se mostrarán en la barra lateral en estas secciones.
Aquí tienes un ejemplo de un tema índice para empezar:
Puedes empezar con una descripción breve 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 generará una barra lateral de documentación que se verá así:
Consulta el tema índice Documentation > 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
Si bien 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 reportes que resaltan las inconsistencias dentro de los temas índice.
-
Temas no indexados:
example.discourse.com/admin/reports/doc_categories_missing_topics
Este reporte 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 reporte muestra elementos incluidos en el índice que parecen no deberían estar allí. El reporte indicará la razón por la cual el tema se ha incluido en el reporte; por ejemplo, si ha sido eliminado o si está en una categoría diferente a la del tema índice en el que se incluye.
Información adicional
Agregar la cadena in:docs a un término de búsqueda buscará en todas las categorías que estén marcadas para documentación (es decir, que tengan 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 
