|||
-|-|-|
| Resumen | DiscoTOC te permite crear una tabla de contenido para tus temas con un solo clic.
| 
| Vista previa | Beginner's guide to using Discourse Themes (Visita el enlace en una nueva pestaña) |
| Enlace al repositorio | https://github.com/discourse/DiscoTOC
| ¿No estás familiarizado con los temas de Discourse? | Visita la página oficial para la Guía para principiantes sobre el uso de temas de Discourse.
Ejemplo
Escritorio
Móvil
Características
toc = table of contents (tabla de contenido)
- Crea una lista de contenido (toc) con un solo clic a través del botón de configuración encima del menú, según el estado del contenido actual.
- El toc se mostrará siempre en la página, sincronizado con el contenido y los enlaces del tema.
- Cuando te desplazas por los temas de la página actual, la tabla de contenido correspondiente se resaltará (se mostrará en verde).
- Añade atributos a los encabezados (puedes enlazar a contenido específico desde otros temas/publicaciones).
- Al hacer clic en el enlace del tema del toc, el navegador navegará a la posición correspondiente en el contenido principal (desplazamiento sincronizado).
- Añade un enlace copiable a cada encabezado (si lo deseas).
- Soporte RTL.
- El esquema de colores se basa en el esquema de colores que estás utilizando actualmente.
Cómo funciona
Por defecto, los encabezados del contenido actual se marcarán como toc (a través del botón del compositor para realizar la operación anterior). Si tu tema actual está marcado, también se convertirá en toc (esto está relacionado con el nivel del encabezado actual). Todos los encabezados de contenido se convertirán en TOC. Esto significa que la configuración de los encabezados de tu archivo MD debe ser correcta. Si el nivel de tus encabezados es incorrecto, el resultado de la conversión también será erróneo.
# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6
Puedes ajustar los niveles libremente, pero debes asegurarte de que los niveles sean correctos.
# heading 2
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2
etc...
Para que los enlaces funcionen, todos los encabezados deben tener un atributo Id.
Este componente verificará automáticamente el Id del encabezado. Si el encabezado existe, el componente funcionará de manera más efectiva. El Id también es más útil cuando creas temas manualmente.
Si tu encabezado no tiene Id, este componente creará automáticamente un Id basado en el contenido del encabezado (se ignorarán los caracteres innecesarios).
Una vez completado todo lo anterior, el TOC creará un enlace al contenido principal basado en los encabezados, como se muestra a continuación:
Configuración
Este componente solo tiene una configuración: el icono del Toc (esta imagen se utilizará en la configuración posterior, y el oficial no recomienda modificar este icono).
Traducción y localización
Este componente requiere muy poco contenido para traducir, solo los siguientes 3 campos necesitan traducción.
table_of_contents: "table of contents (tabla de contenido)"
Esto se mostrará al abrir el TOC en dispositivos móviles.
insert_table_of_contents: "Insert table of contents (Insertar tabla de contenido)"
Esto se mostrará cuando la tabla de contenido se inserte en la página del tema.
topic_will_contain_a_table_of_contents: "This topic will contain a table of contents (Este tema contendrá una tabla de contenido)"
Esto se mostrará en la página de vista previa cuando edites el contenido del tema y lo previsualices a la derecha.
Cómo crear un encabezado
- Los encabezados del contenido deben crearse con la sintaxis correcta.
- Haz clic en la opción de menú de la página (esto solo se mostrará para temas y publicaciones regulares; no se mostrará si estás respondiendo o enviando un mensaje privado).
- Insértalo en la página del tema.
¿Qué sucede con el widget de progreso de lectura cuando usamos Toc?
Como quizás sepas, no podemos mostrar el progreso de lectura y el TOC al mismo tiempo en la página.
La solución oficial es que si el TOC está presente al leer la primera publicación, solo se mostrará el TOC en la página, y el widget de progreso de lectura se ignorará y no se mostrará.
Cuando te desplazas más allá de la primera publicación, el TOC no se mostrará; en su lugar, se mostrará la barra de progreso de lectura de todo el contenido.
En resumen, el TOC solo es válido para la primera publicación; las publicaciones posteriores utilizarán la barra de progreso de lectura.
La visualización es la misma para dispositivos móviles y aplicaciones de escritorio.
¿Hay algún problema al usar este componente?
Según los autores y el oficial, no se han encontrado problemas al usar este componente.
Toda la visualización del contenido se realiza en el lado del cliente, en jerga técnica, todo el contenido se realiza en el frontend, por lo que la provisión de datos del backend no se ve afectada.
Cuando deshabilitas este componente, todo el contenido volverá a su estado original.
Restricciones de uso
Este componente utiliza el diseño de tema estándar.
Si tu diseño ha modificado el uso de encabezados, este componente TOC no funcionará correctamente.
Por ejemplo, se sabe que este componente no funciona correctamente cuando se utiliza el tema Vincent.
El soporte para temas populares es algo que el oficial considerará en el futuro y en la dirección opuesta.
Desarrollador
El autor oficial se basa en la biblioteca tocify.js de Greg Franko.
Sin embargo, desafortunadamente, esta biblioteca no se ha actualizado en mucho tiempo, por lo que el autor ha eliminado mucho contenido innecesario y características y código innecesarios de la biblioteca y ha integrado las características relacionadas en Discourse.
El tamaño total del componente es de aproximadamente ~4kb (con compresión gzip).
El autor también agradece a @erlend_sh por sus excelentes sugerencias y a @david por ayudar con la traducción.
A mejorar (TODO)
- Mostrar TOC en tiempo real durante la edición (esto puede consumir muchos recursos).
- Soporte para temas populares para mostrar TOC.
- Copiar automáticamente al portapapeles el enlace del botón del encabezado al hacer clic.
Con respecto a la publicación de esta versión, el autor indica que es una versión temprana. Si tienes alguna pregunta o sugerencia para este componente, te invitamos a contactar directamente al autor original.
Para las instrucciones oficiales y enlaces relacionados con este componente, consulta la página: DiscoTOC - automatic table of contents.
Ayuda técnica (chino)
Si tienes alguna otra pregunta o necesitas ayuda, visita nuestro sitio web (chino): iSharkFly - 飞鲨