or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdremarkable-plugin.mdtoc-generation.mdtoc-insertion.mdutility-functions.md
tile.json

tessl/npm-markdown-toc

Generate a markdown TOC (table of contents) with Remarkable

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/markdown-toc@1.2.x

To install, run

npx @tessl/cli install tessl/npm-markdown-toc@1.2.0

index.mddocs/

Markdown TOC

Markdown TOC is a JavaScript library that generates table of contents (TOC) for Markdown documents using the Remarkable parser. It provides both a programmatic API and command-line interface for creating navigable table of contents with customizable formatting, depth limits, and filtering capabilities.

Package Information

  • Package Name: markdown-toc
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install markdown-toc

Core Imports

const toc = require('markdown-toc');

For ES modules:

import toc from 'markdown-toc';

Basic Usage

const toc = require('markdown-toc');

// Generate TOC from markdown string
const result = toc('# One\n\n## Two\n\n### Three');
console.log(result.content);
// Output:
// - [One](#one)
//   - [Two](#two)
//     - [Three](#three)

// Access structured data
console.log(result.json);
// Output: [
//   { content: 'One', slug: 'one', lvl: 1 },
//   { content: 'Two', slug: 'two', lvl: 2 },
//   { content: 'Three', slug: 'three', lvl: 3 }
// ]

Architecture

Markdown TOC is built around several key components:

  • Core TOC Generator: Main toc() function that processes markdown and returns structured TOC data
  • Remarkable Integration: Plugin interface for using with Remarkable markdown parser instances
  • CLI Interface: Command-line tool for file processing and TOC injection
  • Insertion System: Functionality to inject TOCs into existing markdown files between HTML comments
  • Utility Functions: Helper functions for slugification, linking, and text processing

Capabilities

TOC Generation

Core table of contents generation from markdown strings with full control over formatting and structure.

/**
 * Generate a markdown table of contents from markdown string
 * @param {string} str - Markdown content to parse for headings
 * @param {Object} options - Configuration options
 * @returns {Object} Result object with content, json, highest, and tokens properties
 */
function toc(str, options);

interface TocResult {
  /** Generated table of contents markdown */
  content: string;
  /** Array of heading objects for custom rendering */
  json: HeadingObject[];
  /** Highest heading level found (used for indentation) */
  highest: number;
  /** Raw Remarkable tokens */
  tokens: any[];
}

interface HeadingObject {
  /** Heading text content */
  content: string;
  /** URL-safe slug for linking */
  slug: string;
  /** Heading level (1-6) */
  lvl: number;
  /** Index in headings array */
  i: number;
  /** Counter for duplicate headings */
  seen: number;
}

TOC Generation

JSON Data Access

Access structured heading data from TOC generation results for custom rendering.

// Access json property on toc() result
const result = toc(markdown);
const headingData = result.json; // Array of HeadingObject

The json property contains the same HeadingObject[] structure as documented in TOC Generation.

TOC Insertion

Insert table of contents into existing markdown files using HTML comment markers.

/**
 * Insert TOC into markdown content between comment markers
 * @param {string} str - Markdown content with TOC markers
 * @param {Object} options - Configuration options
 * @returns {string} Markdown with TOC inserted or replaced
 */
function insert(str, options);

TOC Insertion

Remarkable Plugin

Use as a plugin with Remarkable markdown parser instances for integrated TOC generation.

/**
 * Create Remarkable plugin for TOC generation
 * @param {Object} options - Plugin configuration options
 * @returns {Function} Plugin function for Remarkable.use()
 */
function plugin(options);

Remarkable Plugin

Utility Functions

Helper functions for custom TOC rendering and text processing.

/**
 * Generate URL-safe slug from heading text
 * @param {string} str - Text to slugify
 * @param {Object} options - Slugify options
 * @returns {string} URL-safe slug
 */
function slugify(str, options);

/**
 * Convert heading into markdown link
 * @param {Object} token - Heading token object
 * @param {Object} options - Linking options
 * @returns {Object} Token with linkified content
 */
function linkify(token, options);

/**
 * Render bullet list from heading tokens
 * @param {Array} tokens - Array of heading tokens
 * @param {Object} options - Bullet formatting options
 * @returns {string} Formatted bullet list markdown
 */
function bullets(tokens, options);

/**
 * Process and clean heading text for display
 * @param {string} str - Heading text to process
 * @param {Object} options - Processing options
 * @returns {string} Cleaned heading text
 */
function titleize(str, options);

/**
 * Strip specified words or characters from heading text
 * @param {string} str - Text to process
 * @param {Object} options - Strip configuration
 * @returns {string} Processed text
 */
function strip(str, options);

Utility Functions

Command Line Interface

Command-line tool for processing markdown files and generating TOCs.

# Basic TOC generation
markdown-toc README.md

# Inject TOC into file
markdown-toc -i README.md

# Generate JSON output
markdown-toc --json README.md

# Custom options
markdown-toc --maxdepth 3 --bullets "*" --append "_(Generated by markdown-toc)_" README.md

Command Line Interface

Types

interface TocOptions {
  /** Exclude first H1 heading (default: true) */
  firsth1?: boolean;
  /** Maximum heading depth to include (default: 6) */
  maxdepth?: number;
  /** Bullet characters for list items (default: '*') */
  bullets?: string | string[];
  /** Text to append to end of TOC */
  append?: string;
  /** Enable/customize linking (default: true) */
  linkify?: boolean | Function;
  /** Strip HTML tags from headings (default: true) */
  stripHeadingTags?: boolean;
  /** Filter function for headings */
  filter?: (str: string, element: Object, arr: Array) => boolean;
  /** Custom slugify function */
  slugify?: Function | boolean;
  /** Custom titleize function */
  titleize?: Function | boolean;
  /** Text stripping configuration */
  strip?: Function | Array | string;
}

interface InsertOptions extends TocOptions {
  /** Regex for TOC markers */
  regex?: RegExp;
  /** Opening TOC marker */
  open?: string;
  /** Closing TOC marker */
  close?: string;
  /** Pre-generated TOC content */
  toc?: string;
}