Documentación de Discourse

[Discourse]

Este plugin está siendo retirado en favor del plugin experimental Doc Categories. Seguiremos dando soporte a Docs hasta que el nuevo plugin deje de considerarse experimental.

|||
-|-|-|
| Resumen | Discourse Docs proporciona la capacidad de buscar y filtrar temas de la base de conocimientos
| Enlace al repositorio | https://github.com/discourse/discourse-docs
| Guía de instalación | Cómo instalar plugins en Discourse

Al ser un plugin #oficial mantenido por el equipo de Discourse, las solicitudes de Support, Contribute > Bug, Contribute > UX y Contribute > Feature pueden realizarse en las respectivas categorías aquí en Meta, y etiquetarse con la etiqueta de plugin correspondiente. Haz clic en un enlace a continuación para comenzar uno.

 Soporte  Error  UX  Función

Características

El plugin Discourse Docs es una herramienta poderosa que transforma tu foro de Discourse en una base de conocimientos impulsada por la comunidad. Proporciona una sección dedicada de Docs donde los usuarios pueden crear, actualizar y curar documentación. Este plugin incluye un botón Docs que permite un fácil acceso a esta sección. Es una excelente manera de aprovechar el conocimiento colectivo de tu comunidad y proporcionar un recurso centralizado para información importante.

En esencia, Docs permite una mayor visibilidad de temas de estilo base de conocimientos a través de un conjunto definido de categorías y/o etiquetas.

Filtra la lista por etiquetas, busca a través de la barra de búsqueda y haz clic en los temas para ver la primera publicación, todo sin salir del contexto del explorador de conocimientos.

¿Necesitas encontrar un tema de la base de conocimientos desde otro lugar en Discourse? Usa el nuevo asistente de búsqueda: in:kb.

Configuración

1. Habilita el plugin activando la configuración docs enabled.

2. Agrega categorías y etiquetas a las configuraciones docs categories y docs tags.

3. Encuentra el enlace de Docs en el menú de navegación.

4. ¡Aprovecha el acceso más fácil al conocimiento!

Configuraciones

Nombre	Descripción
docs enabled	Habilita el plugin Docs
docs categories	Una lista de slugs de categorías para incluir en docs
show tags by group	Organiza etiquetas usando Grupos de Etiquetas. Crea grupos para categorizar etiquetas relacionadas.
docs tag groups	Los Grupos de Etiquetas usados para mostrar etiquetas por grupo
docs tags	Una lista de etiquetas para incluir en docs
docs add solved filter	Agrega un filtro para temas resueltos – requiere que Discourse Solved esté instalado y habilitado
docs add to top menu	Agrega un enlace al menú superior para navegar a la vista de Docs
docs add search menu tip	Agrega el consejo “in:docs” a los consejos aleatorios del menú de búsqueda

Combinaciones útiles

Filtro de tarjetas de Discourse Docs

Resumen Discourse Docs Card Filter debe utilizarse con el Discourse Docs Plugin y te permite colocar “Tarjetas” que actúan como un filtro clickeable para obtener resultados de filtrado más rápidos al ingresar a la página /docs por parte de tus usuarios. Vista previa Vista previa en Discourse Theme Creator Enlace al repositorio https://github.com/discourse/discourse-docs-card-filter ¿Nuevo en los temas de Discourse? Guía p…

Renombrar la ruta /docs

Si tienes acceso a tu servidor, puedes cambiar la ruta de tu enlace /docs agregando una variable de entorno DISCOURSE_DOCS_PATH: a tu app.yml:

Para que el cambio surta efecto, puedes ejecutar ./launcher rebuild app o, como es una variable de entorno, puedes ejecutar ./launcher destroy app && ./launcher start app para minimizar el tiempo de inactividad. Hay un poco más de información al respecto aquí: Set Environmental Variables

También es posible que quieras cambiar el texto de visualización del sitio para que coincida. Puedes buscar todas las instancias de ‘docs’ desde tu página /admin/customize/site_texts, pero las principales serían:

• js.docs.title
• js.sidebar.docs_link_text

¿Alojado por nosotros? Renombrar la ruta /docs solo está disponible en nuestro plan Enterprise. Contáctanos si deseas obtener más información.

Historial de desarrollo

El plugin Docs fue una continuación del Componente Temático Knowledge Explorer.

[Hyan]

Hola comunidad de Discourse,

Recibí el siguiente error al ejecutar la especificación. No cambié ningún archivo. ¿Puedo ignorar este error?

➜  discourse git:(main) ✗ LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-docs/spec

Randomized with seed 57815
...................................F

Failures:

  1) Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts
     Failure/Error: expect(page).to have_css(".topic-excerpt", text: topic_1.excerpt)
       expected to find css ".topic-excerpt" but there were no matches

     [Screenshot Image]: /xxxx/discourse/discourse/tmp/capybara/failures_r_spec_example_groups_discourse_docs_index_topic_excerpts_when_the_theme_modifier_serialize_topic_excerpts_is_true_shows_the_excerpts_460.png

     ~~~~~~~ JS LOGS ~~~~~~~
     ~~~~~ END JS LOGS ~~~~

     # ./plugins/discourse-docs/spec/system/docs_index_spec.rb:52:in `block (4 levels) in <main>'
     # ./spec/rails_helper.rb:469:in `block (2 levels) in <top (required)>'

Finished in 13.16 seconds (files took 2.79 seconds to load)
36 examples, 1 failure

Failed examples:

rspec ./plugins/discourse-docs/spec/system/docs_index_spec.rb:50 # Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts

Randomized with seed 57815

[JammyDodger]

¿Pudiste resolver esto @Hyan?

[tpetrov (Toni Petrov)]

Hola Sam, ¿no tendría sentido desde la perspectiva de SEO que el rel=canonical de los temas apunte al tema original? Por ejemplo, Dark/Light Mode Toggle - theme-component - Docs - Discourse Meta → Dark/Light Mode Toggle - theme-component - Discourse Meta? Me pregunto si las dos versiones de la página no se canibalizan entre sí en los algoritmos de Google.

[sam (Sam Saffron)]

Sí, absolutamente deberíamos hacer algo allí

[Hyan]

Lo siento @JammyDodger, no he tenido la oportunidad de ejecutar las especificaciones estos días. No me enfoco en el trabajo relacionado con Discourse Docs, sino en otras cosas estos días. Pero te avisaré cuando tenga alguna oportunidad.

[martyn_thomas]

¿Hay alguna forma de cambiar el icono junto a Documentos en el Menú Hamburguesa del enlace/cadena a otra cosa?

[martyn_thomas]

Este plugin es excelente para tener todas nuestras categorías de documentos en un solo lugar, eliminando la necesidad de que también se listen en la lista de Categorías (gracias a Discourse Category Hider). Sin embargo, hemos notado un problema:

Dentro del plugin/pantalla de Documentos, no se pueden editar documentos existentes ni crear nuevos, lo que significa que tienes que ir a la categoría original para encontrar el tema/documento para editarlo… lo que implica tener el documento accesible en más de un lugar.

¿Hay alguna forma de habilitar la edición de temas/documentos (si el usuario pertenece al Grupo de Usuarios correcto) dentro del plugin de Documentos?

[Moin]

@martyn_thomas

tienes que ir a la categoría original, para encontrar el tema/documento para editarlo

¿Funciona usar el enlace “ver la discusión sobre este tema” en la parte inferior para navegar a ese tema y editarlo?

[digitaldominica]

Hola, tengo un problema que es realmente molesto y no sé por qué está sucediendo.

Cuando creo un documento, va al área de documentos y funciona como se supone que debe hacerlo; sin embargo, si el documento se edita de alguna manera, el diseño del tema de la lista de documentos vuelve al diseño predeterminado del tema de Discourse al hacer clic y no muestra el diseño real del documento.

He notado que después de unos minutos, vuelve al diseño del documento del tema y se ve como se supone que debe verse, ¿hay algo que pueda estar causando esto?

Nota: también uso el componente de tema “Miniaturas de temas” y lo configuro en el modo de miniatura de documentos “lista”.

[digitaldominica]

Encontré el problema, aparentemente si uso Topic List Excerpts o el componente temático Topic lists Thumbnails, el href en el que se puede hacer clic es para la página del tema de discourse y no para docs?topic=xxx de los KB, por lo que me redirige a los temas de discourse.

¿Hay alguna forma de mantener la ruta de la URL en los docs para docs @sam o debería contactar a @david?

[civitas_john (John Chen)]

Hola,

Nuestros usuarios notaron recientemente un pequeño problema de estilo: cuando el navegador tiene menos ancho de ventana gráfica, el contenido de cada publicación de documentación se desbordará, como en la siguiente captura de pantalla:

Me pregunto si sería mejor colapsar automáticamente la barra lateral, si la ventana gráfica es menos que ideal; sin embargo, incluso si colapsara la barra lateral, el contenido aún se desbordaría.

[Nebthtet]

Gracias por el maravilloso complemento. Sin embargo, tengo una pregunta: ¿hay una opción para eliminar el enlace del menú hamburguesa contextual? Lo agregué manualmente en la sección siempre visible (ya que queremos usar esta funcionalidad para mostrar contenido creado por el usuario en formato largo, como artículos, etc.) y ahora termina apareciendo dos veces:

Ambas opciones con fondo más claro llevan a /docs

[Arkshine]

Creo que puedes ocultarlo con algo de CSS aquí:

.sidebar-section-link-wrapper[data-list-item-name=\"docs\"] {
    display: none;
}

[Nebthtet]

¡Funcionó perfectamente! ¡Muchas gracias!

[rly]

¿Hay alguna posibilidad de que tengamos una opción para integrar los comentarios en una página de documentación en lugar de enlazar a la publicación y luego poder comentar?

[wsxiaolin]

@civitas_john

Incluso si colapso la barra lateral, el contenido todavía se desborda.

Volví a visitar el mismo enlace en un dispositivo con el mismo ancho de ventana gráfica. Si bien todavía había desbordamiento antes de colapsar la barra lateral, descubrí que después de colapsarla, no hay desbordamiento y la visualización es normal y estéticamente agradable.

[supermathie (Michael Brown)]

Me sorprende que el orden de búsqueda predeterminado en Docs no sea “Relevancia”, sino “Fecha de actividad”.

¿Es posible buscar por relevancia?

[thaidb]

Hoy publiqué algunos temas en la categoría de Documentos, pero esos temas no se muestran en la página de Documentos. Desactivé el complemento de Documentos y volví a activar el tema, pero esos temas aún no se muestran.
¡Gracias!