 |
Resumen | DiscoTOC te permitirá generar un índice interactivo para tus temas con un solo clic. |
 |
Vista previa | Vista previa en Discourse Theme Creator |
 |
Enlace al repositorio | https://github.com/discourse/DiscoTOC |
 |
¿Eres nuevo en los temas de Discourse? | Guía para principiantes sobre el uso de temas de Discourse |
Instalar este componente de tema
Ejemplos
Escritorio
Móvil
Características
toc = índice
-
Genera automáticamente todo el índice mediante un botón en el menú de engranajes del compositor
-
El índice siempre estará en la pantalla: se desplazará con el contenido como el widget de progreso del tema
-
A medida que te desplaces por las secciones del tema, el elemento activo en el índice se marcará como activo (resaltado en azul)
-
Cada entrada del índice enlaza al ancla del encabezado, por lo que también puedes enlazar a una sección específica desde otro tema o publicación
-
Hacer clic en cualquier enlace del índice indicará al navegador que navegue a la sección correspondiente (desplazamiento suave)
-
En temas con respuestas, un botón Contenido / Cronología permite a los lectores cambiar entre el índice y la cronología normal del tema. La elección se recuerda en el navegador
-
Compatible con el complemento Discourse Docs
-
Soporte opcional para índices en respuestas, no solo en la primera publicación
-
Compatibilidad con RTL (de derecha a izquierda)
¿Cómo funciona?
En resumen, busca encabezados en los temas que estén marcados para tener un índice (a través del botón del compositor) y, si resulta que el tema actual está marcado, toma todos los encabezados y los coloca en el índice (anidados en orden de niveles de encabezado): esto significa que tu Markdown debe ser sintácticamente correcto.
# encabezado 1
## encabezado 2
### encabezado 3
#### encabezado 4
##### encabezado 5
Eres libre de subir y bajar en los niveles de encabezado, pero el orden debe ser correcto.
# encabezado 2
## encabezado 3
## encabezado 3
### encabezado 4
## encabezado 3
# encabezado 2
etc...
Algunas cosas que debes saber sobre qué encabezados son compatibles:
- Se incluyen
h1hastah5.h6no se incluye. - Los encabezados dentro de citas se ignoran, por lo que las citas no ensuciarán el índice.
- El índice solo aparece si la publicación tiene al menos tantos encabezados como indique la configuración de Mínimo de encabezados para el índice (3 por defecto).
¿Cómo funcionan los enlaces en el índice?
Cada encabezado en una publicación cocida obtiene una ancla en la forma p-<id de publicación>-<slug del encabezado>-<número>: es el objetivo detrás de un encabezado. DiscoTOC enlaza a esas anclas en lugar de inventar las suyas propias.
Como esas anclas incluyen la posición del encabezado en la publicación, cambian si reordenas o retitulás encabezados. Si estás enlazando a secciones desde otro lugar, puedes agregar anclas nombradas estables encima del encabezado:
<div><a name="mi-seccion"></a></div>
## Mi sección
Luego enlaza a /t/tu-slug-de-tema/1234#mi-seccion. Discourse permite <a name="..."> en las publicaciones. Las propias entradas de DiscoTOC seguirán usando las anclas principales de los encabezados, pero las tuyas seguirán funcionando independientemente de las ediciones.
Configuración
| Nombre | Descripción |
|---|---|
| nivel mínimo de confianza para crear índice | Lo que se debe tener para ver el botón de índice en el compositor |
| texto del índice del compositor | Texto que aparece en la parte superior del compositor para indicar que el tema tendrá un índice |
| categorías de índice automático | Habilita automáticamente las categorías |
| etiquetas de índice automático | Habilita automáticamente el índice en temas con estas etiquetas |
| habilitar índice para respuestas | Permite índices en respuestas. Los índices de las respuestas no se ven afectados por las configuraciones de etiquetas de índice automático y categorías de índice automático y deben insertarse manualmente |
| mínimo de encabezados para el índice | Número mínimo de encabezados en un tema para que se muestre el índice |
texto del índice del compositor es lo que aparece en la vista previa del compositor para indicar que se generará un índice:
Traducciones
| Traducción | Predeterminado |
|---|---|
| table_of_contents | índice |
| insert_table_of_contents | Insertar índice |
| jump_bottom | Ir al final |
| toggle_toc.show_timeline | Cronología |
| toggle_toc.show_toc | Contenido |
table_of_contents: "índice"
esto se usa para el botón que abre el índice en dispositivos móviles
insert_table_of_contents: "Insertar índice"
esto se usa como texto para el botón de índice en el menú de engranajes del compositor
toggle_toc.show_toc: "Contenido"
toggle_toc.show_timeline: "Cronología"
estos etiquetan el botón que cambia entre el índice y la cronología del tema
¿Cómo creo un índice?
- Escribe un tema con encabezados sintácticamente correctos.
- Haz clic en el botón de índice en el menú de engranajes del compositor. Por defecto, solo aparece en la primera publicación de un tema; habilita la configuración habilitar índice para respuestas para usarlo también en respuestas.
- ¡Listo!
¿Qué le sucede al widget de progreso del tema cuando un tema tiene un índice?
No hay espacio para mostrar ambos al mismo tiempo, por lo que en un tema con índice, el widget de progreso del tema se oculta mientras estás en la primera publicación, y ves el índice en su lugar. Una vez que te desplazas más allá de la primera publicación, el índice se reemplaza por el widget de progreso del tema regular mientras lees las respuestas. (Con habilitar índice para respuestas activado, una respuesta que tenga su propio índice mostrará ese en su lugar).
En temas con más de una publicación, un botón Contenido / Cronología permite a los lectores cambiar entre los dos, y la preferencia se recuerda en su navegador.
En pantallas estrechas, el índice se abre como una superposición a través de un botón en el área de progreso del tema.
¿Hay alguna desventaja en usar este componente?
Casi todo ocurre en el lado del cliente, por lo que puedes eliminar el componente en cualquier momento y tus publicaciones se renderizarán como lo hacían antes. La única cosa que toca tu contenido es el botón del compositor: envuelve la publicación en un marcador <div data-theme-toc="true">, que es cómo el componente sabe que la publicación debe tener un índice. Si desinstalas el componente, ese envoltorio permanece en la publicación pero no tiene efecto visible.
Limitaciones
Los encabezados h6 y los encabezados dentro de citas no se incluyen en el índice.
Crédito
Esto comenzó como una bifurcación dura de la biblioteca tocify.js de Greg Franko, y desde entonces se ha reescrito como componentes nativos de Ember. No hay dependencias externas ni solicitudes.
Un gran agradecimiento a @erlend_sh por toda la valiosa retroalimentación y a @david por su ayuda con las traducciones.
¡gracias!
