remark-toc-inline

A remark plugin that allows you to specify Table of Contents options inline in your markdown files, overriding global TOC settings on a per-page basis.

Installation

npm install remark-toc-inline remark-toc

Usage

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkTocInline from 'remark-toc-inline';
import remarkStringify from 'remark-stringify';

const processor = unified().use(remarkParse).use(remarkTocInline).use(remarkStringify);

const markdown = `
# My Document

Table of Contents { "maxDepth": 3, "tight": true }

## Section 1
## Section 2
`;

const result = await processor.process(markdown);
console.log(String(result));

Markdown Syntax

In your markdown files, use the following syntax to configure TOC options:

Table of Contents { "maxDepth": 3, "tight": true }

The JSON object can contain any options supported by remark-toc.

Common Options

• maxDepth - Maximum heading depth to include (e.g., 3 for h1-h3)
• tight - Whether to use tight list spacing
• ordered - Whether to use an ordered list
• skip - Pattern to skip certain headings

Plugin Options

title

Type: string Default: "Table of Contents"

Custom title/heading to match for TOC insertion.

.use(remarkTocInline, { title: "Contents" })

Then in your markdown:

Contents { "maxDepth": 2 }

normalizeQuotes

Type: boolean Default: true

Whether to normalize curly quotes to straight quotes in JSON options. This is useful for handling copy-paste issues from rich text editors (like Word or Google Docs).

.use(remarkTocInline, { normalizeQuotes: true })

With this enabled, both of these will work:

Table of Contents { "maxDepth": 3 }
Table of Contents { "maxDepth": 3 } <!-- curly quotes -->

Examples

Basic Usage

# My Guide

Table of Contents

## Introduction

## Getting Started

## Advanced Topics

With Custom Options

# API Reference

Table of Contents { "maxDepth": 2, "tight": true, "ordered": true }

## Authentication

### API Keys

### OAuth

## Endpoints

### Users

### Posts

Custom Title

.use(remarkTocInline, { title: "Contents" })

# Documentation

Contents { "maxDepth": 3 }

## Overview

## Installation

## Usage

Development

Testing

This package includes a comprehensive test suite using Vitest.

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

Building

npm run build

License

MIT