Hi everyone! 
I’ve been working on a lightweight solution for adding automatic table of contents to Ghost posts, and I’d love to share it with the community. It’s completely free and open source (MIT License).
What is Ghost TOC?
Ghost TOC is a simple JavaScript script that automatically generates a table of contents from your article headings. Just add a <toc> tag where you want the TOC to appear, and it builds itself from your H2-H6 headings.
Example of Ghost TOC in action on a blog post:
Why I Built This
Ghost doesn’t have built-in TOC functionality, and existing solutions either required external dependencies, only worked in sidebars, or needed server file modifications. I wanted something that lives inside the post content itself:
No external dependencies- Places TOC directly in your post content (not a sidebar widget)
- Install once via Code Injection, use everywhere
- Just add
<toc>tag wherever you want it in your article
Key Features
Lives inside your post content (place it anywhere in your article)
Automatic generation from H2-H6 headings
Collapsible with show/hide toggle
Customizable colors and styling
Multi-language support (customize the title)
Database efficient - no script duplication per post
Lightweight (~2KB minified)
Quick Example
In your Ghost post editor, add an HTML block and insert:
<!-- Simple TOC -->
<toc title="Table of Contents"></toc>
<!-- Collapsible with custom colors -->
<toc
title="What You'll Learn"
collapsible="true"
show-text="Show Contents"
hide-text="Hide Contents"
border-color="#3498db"
bg-color="#ecf0f1">
</toc>
The TOC appears right where you place the tag - typically after your intro paragraph, before the main content.
Installation
- Copy the script from dist/ghost-toc.min.js (click “Copy raw file” button)
- Go to Ghost Admin → Settings → Code Injection
- Paste into Site Footer
- Save and you’re done!
Now just add <toc> tags to your posts and save them as snippets for quick reuse.
Note: This project evolved from my original blog post, but the GitHub repository now has complete installation instructions, examples, and documentation - everything you need is there!
Repository
The project is now on GitHub with full documentation and examples:
The repository includes:
- Complete installation guide
- Working examples (basic, collapsible, full customization)
- Build system and GitHub Actions automation
- Comprehensive documentation
Try It Out
Check out the examples to see it in action, or view it live on my blog.
Would love to hear your feedback or ideas for improvements!
Happy blogging!
I wanted a quick solution for myself, so I created a TOC snippet and reuse it for every post. Ideally, I should update the theme’s post template to fix the TOC in a consistent position across all posts. However, since I occasionally write in two languages, that approach isn’t ideal for me. I’d likely need an additional script to detect the post’s language and apply the correct TOC title.
Filter headings
Start collapsed
Numbered lists
Skip sections
