ghost-toc

Quick Start Guide

Get Ghost TOC up and running in 5 minutes.

Upgrading from Gist? This repository replaces the older Gist versions (v1.0, v2.1). Just swap the old script for the new one - everything else stays the same!

Step 1: Install the Script (2 minutes)

1. Open dist/ghost-toc.min.js in this repository
2. Copy the entire contents (including <script> tags)
3. Go to your Ghost Admin → Settings → Code Injection
4. Paste into Site Footer
5. Click Save

✅ Done! The script is now active on your entire blog.

Step 2: Add TOC to a Post (1 minute)

1. Open any post in Ghost editor
2. Click + to add a new block
3. Select HTML block
4. Add this code:

   <toc title="Table of Contents"></toc>
   

5. Publish your post

✅ Your TOC will appear automatically!

Step 3: Create a Reusable Snippet (2 minutes)

Instead of typing the TOC code every time:

1. With your HTML block selected (from Step 2)
2. Click the ⋮ (three dots) menu
3. Select Save as snippet
4. Name it “TOC”

✅ Now you can add TOC to any post by typing /TOC

💡 New to Ghost snippets? Learn more about how snippets work in Ghost’s official snippets guide.

Common Configurations

Simple TOC

<toc title="Contents"></toc>

Collapsible TOC

<toc
  title="Table of Contents"
  collapsible="true"
  show-text="Show"
  hide-text="Hide">
</toc>

Styled Collapsible TOC

<toc
  title="In This Article"
  collapsible="true"
  show-text="▼ Expand"
  hide-text="▲ Collapse"
  border-color="#e0e0e0"
  bg-color="#f9f9f9">
</toc>

Smart TOC (Remembers State)

<toc
  title="Contents"
  collapsible="true"
  default-state="collapsed"
  remember-state="true">
</toc>

Filtered TOC (Only H2 and H3)

<toc
  title="Quick Navigation"
  levels="2,3">
</toc>

Numbered TOC

<toc
  title="Steps in This Tutorial"
  list-style="numbers">
</toc>

Multi-language TOC

Save different snippets for each language:

• English: <toc title="Table of Contents"></toc>
• Spanish: <toc title="Tabla de Contenidos"></toc>
• German: <toc title="Inhaltsverzeichnis"></toc>
• French: <toc title="Table des Matières"></toc>

How It Works

Ghost TOC automatically:

1. Finds all headings (H2, H3, H4, H5, H6) in your article
2. Builds a nested list structure
3. Creates clickable links that jump to each section
4. Filters out Ghost’s author name heading

Tips

💡 Place TOC after your intro: Add the TOC after your opening paragraphs, before the main content

💡 Use descriptive headings: Your TOC is only as good as your heading structure

💡 Test in preview: Always preview your post to verify TOC appears correctly

💡 Heading IDs required: Ghost automatically adds IDs to headings - if links don’t work, check that headings have id attributes

Troubleshooting

TOC doesn’t appear

• Check browser console (F12) for errors
• Verify script is in Site Footer (not header)
• Ensure you’re using lowercase <toc> not <TOC>

Links don’t work

• Ghost should automatically add IDs to headings
• If using custom HTML headings, add IDs manually: <h2 id="my-section">My Section</h2>

Styling looks wrong

• Your theme CSS might conflict - check browser inspector
• Add custom CSS in Code Injection if needed

Next Steps

• 📖 Read the full installation guide for advanced options
• 🔍 Check examples for working demos
• 🎨 Customize styling to match your theme
• 📚 See README for all configuration options

Need Help?

• Check the troubleshooting section in the installation guide
• Review the examples directory
• Open an issue on GitHub

---

Time invested: 5 minutes

Benefit: Enhanced navigation for all your blog posts 🚀

This site is open source. Improve this page.