Prévia do ghost-toc-plugin

Altere as opções no painel à esquerda. O índice é renderizado em tempo real e o código de incorporação é atualizado junto. Role para ver a seção atual destacada.

Introdução

ghost-toc-plugin é um índice flutuante minúsculo (~3 KB) e sem dependências para o Ghost. Começou como um widget para o Ghost, mas também funciona em blogs baseados em Notion e em qualquer lugar onde você possa adicionar um script. Ele lê os títulos do seu artigo, monta a lista automaticamente, acompanha a rolagem e destaca a seção que você está lendo. Esta página é um exemplo ao vivo: a lista ao lado é o widget real.

Instalação

Adicione de uma vez com este trecho, sem etapa de build nem arquivos do tema para 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="Conteúdo"></script>

Injeção de código

No Ghost, cole em Settings → Code injection → Site Footer. Em hospedagem baseada em Notion, adicione no campo de código personalizado: o oopy tem uma caixa de código head/footer nas configurações do site, o super.so tem uma área Custom Code, e ali você define data-content como .notion-page-content. Em qualquer outro site, coloque logo antes da tag </body>. Deixe sem async ou defer para que ele leia as próprias opções data-*.

Opções

Tudo é configurado com atributos data-* na tag do script: o seletor de conteúdo, quais títulos incluir, o título, a posição e mais:

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

Personalização

Cores e posição são totalmente ajustáveis. Cada classe e variável CSS fica no namespace greedylabs-ghost-toc, então o widget nunca conflita com o seu tema.

Cores

O item ativo segue, por padrão, a cor de destaque do seu tema Ghost (--ghost-accent-color); use data-accent ou sobrescreva as variáveis CSS para mudá-la. O widget traz valores claros e escuros e se adapta automaticamente ao tema do sistema. Para melhorar a legibilidade no modo escuro, sobrescreva as cores apenas para o escuro, um único valor fixo ficaria estranho no claro:

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

Posição

Use data-position para esquerda ou direita, data-top para o deslocamento do topo, data-gap para o espaço em relação ao conteúdo e data-width para a largura do painel. Abaixo de data-min-width (ou quando não há espaço ao lado) o índice se esconde sozinho.

Perguntas frequentes

O widget deixa meu site mais lento?

Quase nada. Tem cerca de 3KB, sem dependências nem requisições externas. A rolagem é tratada com um listener passivo e agrupada em um único cálculo por quadro via requestAnimationFrame; só recalcula quando a altura do documento muda (imagens com carregamento tardio, giscus e widgets semelhantes) por meio de um ResizeObserver.

Por que o índice não aparece?

Verifique três coisas: se o seu seletor data-content corresponde ao contêiner real do artigo, se há pelo menos dois títulos (abaixo disso ele não é gerado) e se a janela é mais larga que data-min-width (1200px por padrão) com espaço para o painel ao lado do conteúdo. Em telas estreitas e no celular ele se oculta de propósito.

Posso incluir títulos mais profundos como h4 no índice?

Sim. Liste as tags desejadas em data-headings, separadas por vírgula (por exemplo, h2,h3,h4). Você decide exatamente quais níveis de título aparecem na lista.

Conclusão

ghost-toc-plugin é de código aberto sob a licença MIT; o código e as issues estão no GitHub. Experimente as opções no painel à esquerda, veja a prévia atualizar ao vivo e copie o trecho quando gostar. Se ajudou você, um café é sempre bem-vindo ☕.