Markdown TOC

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

import toc from 'markdown-toc';

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 }
// ]

/**
 * 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;
}

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

/**
 * 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);

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

/**
 * 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);

# 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

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;
}