Vista previa de ghost-toc-plugin

Cambia las opciones en el panel izquierdo. El índice se vuelve a renderizar en vivo y el código de inserción se actualiza con él. Desplázate para ver la sección actual resaltada.

Introducción

ghost-toc-plugin es un índice flotante diminuto (~3 KB) y sin dependencias para Ghost. Empezó como un widget para Ghost, pero también funciona en blogs basados en Notion y en cualquier sitio donde puedas añadir un script. Lee los encabezados de tu artículo, crea la lista automáticamente, te sigue al desplazarte y resalta la sección que estás leyendo. Esta página es un ejemplo en vivo: la lista lateral es el widget real.

Instalación

Añádelo una sola vez con este fragmento, sin paso de compilación ni archivos del tema que editar:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.css">
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.min.js"
        data-content=".gh-content"
        data-headings="h2,h3"
        data-title="Contenido"></script>

Inyección de código

En Ghost, pégalo en Settings → Code injection → Site Footer. En hosting basado en Notion, añádelo en el campo de código personalizado: oopy tiene una caja de código head/footer en sus ajustes, super.so tiene un área Custom Code, y ahí pones data-content en .notion-page-content. En cualquier otro sitio, colócalo justo antes de la etiqueta </body>. Déjalo sin async ni defer para que pueda leer sus propias opciones data-*.

Opciones

Todo se configura con atributos data-* en la etiqueta del script: el selector de contenido, qué encabezados incluir, el título, la posición y más:

data-content=".gh-content"
data-headings="h2,h3"
data-position="right"
data-min-width="1200"
data-top="100"

Personalización

Los colores y la ubicación son totalmente ajustables. Cada clase y variable CSS está en el espacio de nombres greedylabs-ghost-toc, así que el widget nunca choca con tu tema.

Colores

El elemento activo sigue por defecto el color de acento de tu tema Ghost (--ghost-accent-color); usa data-accent o sobrescribe las variables CSS para cambiarlo. El widget incluye valores claros y oscuros y se adapta al tema del sistema automáticamente. Para mejorar la legibilidad en modo oscuro, sobrescribe los colores solo para oscuro, un único valor fijo se vería mal en claro:

@media (prefers-color-scheme: dark) {
  .greedylabs-ghost-toc {
    --greedylabs-ghost-toc-muted: #c9d1d9;
    --greedylabs-ghost-toc-border: rgba(255,255,255,.22);
  }
}

Posición

Usa data-position para izquierda o derecha, data-top para el margen superior, data-gap para el espacio respecto al contenido y data-width para el ancho del panel. Por debajo de data-min-width (o cuando no hay espacio al lado) el índice se oculta solo.

Preguntas frecuentes

¿El widget ralentiza mi sitio?

Apenas. Ocupa unos 3KB, sin dependencias ni peticiones externas. El scroll se gestiona con un listener pasivo y se agrupa en un solo cálculo por fotograma con requestAnimationFrame; solo recalcula cuando cambia la altura del documento (imágenes diferidas, giscus y widgets similares) mediante un ResizeObserver.

¿Por qué no aparece la tabla de contenidos?

Comprueba tres cosas: que tu selector data-content coincida con el contenedor real del artículo, que haya al menos dos encabezados (no se genera con menos) y que la ventana sea más ancha que data-min-width (1200px por defecto) con espacio para el panel junto al contenido. En pantallas estrechas y móviles se oculta a propósito.

¿Puedo incluir encabezados más profundos como h4 en el índice?

Sí. Enumera las etiquetas que quieras en data-headings, separadas por comas (por ejemplo, h2,h3,h4). Tú decides exactamente qué niveles de encabezado aparecen en la lista.

Conclusión

ghost-toc-plugin es de código abierto bajo licencia MIT; el código y las incidencias están en GitHub. Prueba las opciones en el panel izquierdo, mira la vista previa actualizarse en vivo y copia el fragmento cuando te guste. Si te ha servido, siempre se agradece un café ☕.