ghost-toc

Ghost TOC

A lightweight, customizable Table of Contents generator for Ghost blog platform.

Note: While designed specifically for Ghost, this script will work on any webpage that has an <article> tag containing heading elements (H2-H6). The Ghost-specific features include filtering out Ghost’s author name heading and integration with Ghost’s code injection system.

Preview

| Ghost TOC Example | See it in action

Ghost TOC automatically generates a hierarchical table of contents from your article headings.

Features shown:
• Clean, minimal design
• Hierarchical structure (H2, H3)
• Clickable navigation links
• Customizable title | |—–|—–|

Features

Installation

  1. Go to your Ghost Admin panel
  2. Navigate to Settings → Code Injection
  3. In the Site Footer section, copy and paste the content from dist/ghost-toc.min.js
  4. Click Save

Manual Installation

Download the dist/ghost-toc.min.js file and include it in your Ghost theme’s footer.

📖 For detailed installation instructions with pro tips, see INSTALLATION.md

⚡ Want to get started quickly? Check out the Quick Start Guide

Usage

Basic Usage

Add the <toc> tag anywhere in your Ghost article where you want the table of contents to appear:

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

Collapsible TOC

Create a collapsible table of contents with custom styling:

<toc
  title="Table of Contents"
  collapsible="true"
  show-text="Show"
  hide-text="Hide"
  border-color="gainsboro"
  bg-color="aliceblue">
</toc>

Configuration Options

Attribute Type Default Description
title string - Title displayed at the top of TOC
collapsible boolean false Enable collapsible functionality
show-text string "Show" Text for expand button
hide-text string "Hide" Text for collapse button
default-state string "expanded" Initial state for collapsible TOC (collapsed or expanded)
levels string "2,3,4,5,6" Comma-separated heading levels to include (e.g., "2,3" for H2 and H3 only)
class string - Custom CSS classes to add to TOC container
remember-state boolean false Persist TOC state in localStorage across page loads
list-style string "bullets" List marker style (bullets, numbers, or none)
exclude string - Comma-separated heading IDs to exclude from TOC
border-color string "gainsboro" Border color for collapsible TOC
bg-color string "aliceblue" Background color for collapsible TOC

🎨 Want more customization options? See the Customization Guide

How It Works

Ghost TOC automatically:

  1. Scans your article for heading elements (H2-H6)
  2. Filters out Ghost’s default author name heading
  3. Validates that headings have id attributes (skips those without, logs warning)
  4. Builds a hierarchical navigation structure
  5. Generates clickable links with anchor navigation
  6. Applies custom styling based on your configuration
  7. Adds ARIA attributes for screen reader accessibility

Examples

See the examples/ directory for complete implementation examples:

Why Use Ghost TOC?

Traditional Approach Problems

Ghost TOC Benefits

Real-World Use Cases

Technical Blogs

Long tutorials and documentation benefit from hierarchical navigation through complex topics.

Multi-language Sites

Easily customize TOC titles per language without maintaining separate scripts:

<!-- English post -->
<toc title="Table of Contents"></toc>

<!-- Spanish post -->
<toc title="Tabla de Contenidos"></toc>

Long-form Content

Articles with multiple sections become more navigable and user-friendly.

Documentation Sites

Perfect for Ghost-powered documentation with structured content.

The Story Behind Ghost TOC

Ghost TOC was born from a simple frustration: Ghost didn’t have built-in table of contents functionality, and the existing solutions weren’t good enough.

The Problem (2024)

When writing comprehensive articles, I needed a way to help readers navigate through sections. Manual TOCs were tedious and error-prone—every time you changed a heading, you had to update the links. The recommended solution, Tocbot, had its own issues:

There had to be a better way.

Version 1.0 - The Beginning

The first version (v1.0 Gist, blog post) solved the core problem:

But there was a catch: the script had to be duplicated in every single post. This meant database bloat and maintenance headaches when updates were needed.

Version 2.0 - The Evolution

V2 (v2.1 Gist, blog post) revolutionized the approach:

Today - The Repository

What started as a Gist has grown into a full-fledged project with:

Ghost TOC proves that sometimes the best solutions come from scratching your own itch. What began as a simple workaround is now used by bloggers worldwide to make their content more navigable and user-friendly.

Migration from Gist

If you’re currently using the Gist version, simply replace it with the code from this repository’s dist/ghost-toc.min.js file. The API and functionality remain the same - no changes needed to your <toc> tags!

Using Outside of Ghost

While Ghost TOC is designed for the Ghost platform, it can be used on any website with the following requirements:

Requirements

  1. Your page must have an <article> tag containing your content
  2. Headings must be properly structured (H2-H6) with id attributes for anchor links
    • Note: Headings without id attributes will be automatically skipped with a console warning
  3. Include the script before the closing </body> tag

Generic HTML Usage

<!DOCTYPE html>
<html>
<head>
    <title>My Article</title>
</head>
<body>
    <article>
        <toc title="Table of Contents"></toc>

        <h2 id="section-1">Section 1</h2>
        <p>Content here...</p>

        <h3 id="subsection-1-1">Subsection 1.1</h3>
        <p>More content...</p>

        <h2 id="section-2">Section 2</h2>
        <p>Content here...</p>
    </article>

    <script src="path/to/ghost-toc.js"></script>
</body>
</html>

WordPress, Drupal, or Static Sites

Simply include the script in your theme’s footer and add the <toc> tag where needed. Most modern CMS platforms automatically generate heading IDs, making this script compatible out of the box.

Development

Building from Source

To build the minified distribution file from source:

# Install dependencies
npm install

# Build minified version
npm run build

This will minify src/ghost-toc.js and output to dist/ghost-toc.min.js.

Automated Workflows

GitHub Actions automatically handles builds:

See .github/workflows/README.md for details.

For detailed build instructions, see BUILD.md.

Project Structure

ghost-toc/
├── src/
│   └── ghost-toc.js              # Source code (edit this)
├── dist/
│   └── ghost-toc.min.js          # Minified distribution (auto-generated)
├── docs/                         # Documentation
├── examples/                     # Working examples
└── scripts/                      # Build scripts

License & Credits

License: MIT License - see LICENSE file for details

Author: Volodymyr Lavrynovych

Community:

This site is open source. Improve this page.