Getting Started - Astro Table of Contents

🚀 Quick Start Guide

Get up and running with Astro Table of Contents in just a few minutes. This guide will walk you through the installation, configuration, and basic usage.

📦 Installation

Install the package using your preferred package manager:

npm i astro-table-of-contents

pnpm add astro-table-of-contents

yarn add astro-table-of-contents

⚙️ Configuration

1. Configure the Integration

Add the table of contents integration to your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import { tableOfContents } from 'astro-table-of-contents';

export default defineConfig({
    integrations: [
        tableOfContents({
            title: 'Table of Contents', // Custom title
        }),
    ],
});

2. Configuration Options

Option	Type	Default	Description
`title`	string	'Table of Contents'	Default title for the TOC

⚠️ SSR Important Note

Configuration Title Limitations

Important: The title configured in astro.config.mjs may not work properly in SSR mode (server-rendered pages). For pages with output: "server" or hybrid mode, you should pass a custom title directly to the component:

<TableOfContents title="My Custom Title" />

If no title is provided via props, the component will use the default "Table of Contents" regardless of the configuration.

🔧 Work in Progress: We are actively working on improving SSR compatibility to make global configuration work seamlessly across all Astro rendering modes in future releases.

🛠️ Basic Usage

Using the TableOfContents Component

Import and use the component in your Astro pages:

---
// In your .astro file
import TableOfContents from 'astro-table-of-contents/component';
---

<html>
  <head>
    <title>My Page with TOC</title>
  </head>
  <body>
    <main>
      <TableOfContents 
        title="Page Contents" 
        backgroundColor="#f8f9fa"
        class="my-toc" 
      />
      
      <h1>Main Title</h1>
      <p>Content goes here...</p>

      <h2>Section 1</h2>
      <p>More content...</p>

      <h3>Subsection 1.1</h3>
      <p>Nested content...</p>

      <h2>Section 2</h2>
      <p>Final content...</p>
    </main>
  </body>
</html>

Component Props

The TableOfContents component accepts the following props:

title (string, optional): Custom title for this specific TOC instance
backgroundColor (string, optional): Custom background color (CSS color value)
class (string, optional): Additional CSS classes for styling

🔧 Advanced Usage

Manual TOC Generation

You can also generate TOC programmatically using the utility functions:

import { generateToc } from 'astro-table-of-contents';

const htmlContent = `
  <h1>Chapter 1: Introduction</h1>
  <h2>1.1 Overview</h2>
  <h3>1.1.1 Background</h3>
  <h2>1.2 Objectives</h2>
`;

const tocOptions = {
  content: htmlContent
};

const tocHtml = generateToc(tocOptions);
console.log(tocHtml);

Custom Styling

Override the default styles by targeting the component classes:

/* Custom TOC styling */
stron-toc {
  border: 2px solid #e2e8f0;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

stron-toc h2 {
  color: #fff;
  border-bottom: 1px solid rgba(255,255,255,0.2);
}

stron-toc a {
  color: #e2e8f0;
  transition: all 0.3s ease;
}

stron-toc a:hover {
  color: #fff;
  padding-left: 0.5rem;
}

🔍 Troubleshooting

Common Issues

Custom title from config not working in SSR

Solution: In SSR mode (server-rendered pages), the title from astro.config.mjs may not be available. Always pass the title as a prop: <TableOfContents title="My Title" />

🚀 Future Update: This limitation is being addressed and will be resolved in upcoming versions to provide better SSR support.

Styling conflicts

Solution: Use more specific CSS selectors or the class prop to avoid conflicts with existing styles.

🎯 Next Steps

📚 API Reference

Explore the complete API documentation with all available methods and configuration options.

View API Docs

🌐 Live Demo

See the table of contents in action with our interactive demo website.

View Demo

💡 Examples

Check out the GitHub repository for more examples and advanced use cases.

GitHub Repo