tessl/npm-markdown-toc

Generate a markdown TOC (table of contents) with Remarkable

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

TOC Generation

Name: tessl/npm-markdown-toc
Author: tessl

Core table of contents generation functionality that processes markdown strings and returns structured TOC data with customizable formatting options.

Capabilities

Main TOC Function

Generate a markdown table of contents from markdown content.

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

Usage Examples:

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

// Basic TOC generation
const result = toc(`
# Introduction
Some content here.

## Getting Started
More content.

### Installation
Installation instructions.

## Usage
Usage examples.
`);

console.log(result.content);
// Output:
// - [Introduction](#introduction)
//   - [Getting Started](#getting-started)
//     - [Installation](#installation)
//   - [Usage](#usage)

// Access structured data
console.log(result.json);
// Output: [
//   { content: 'Introduction', slug: 'introduction', lvl: 1, i: 0, seen: 0 },
//   { content: 'Getting Started', slug: 'getting-started', lvl: 2, i: 1, seen: 0 },
//   { content: 'Installation', slug: 'installation', lvl: 3, i: 2, seen: 0 },
//   { content: 'Usage', slug: 'usage', lvl: 2, i: 3, seen: 0 }
// ]

Result Object Structure

The TOC function returns a comprehensive result object.

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

Configuration Options

Comprehensive options for customizing TOC generation behavior.

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

Usage Examples with Options:

// Limit depth and customize bullets  
const result = toc(markdown, {
  maxdepth: 3,
  bullets: ['-', '*', '+'],
  firsth1: false
});

// Custom filtering
const result = toc(markdown, {
  filter: function(str, ele, arr) {
    // Skip headings containing "internal"
    return str.indexOf('internal') === -1;
  }
});

// Custom slugify function
const result = toc(markdown, {
  slugify: function(str) {
    return str.toLowerCase().replace(/[^\w]/g, '-');
  }
});

// Append footer
const result = toc(markdown, {
  append: '\n\n_(TOC generated automatically)_'
});

Duplicate Heading Handling

Automatic handling of duplicate headings with numbering.

const markdown = `
# Overview
## Setup  
## Setup
## Setup
`;

const result = toc(markdown);
console.log(result.content);
// Output:
// - [Overview](#overview)
//   - [Setup](#setup)
//   - [Setup](#setup-1) 
//   - [Setup](#setup-2)

Front-matter Support

Automatic detection and handling of YAML front-matter.

const markdown = `
---
title: My Document
author: John Doe
---

# Introduction
Content here.

## Usage
More content.
`;

const result = toc(markdown);
// Front-matter is ignored, TOC starts from first actual heading

HTML Tag Stripping

Automatic removal of HTML tags from heading text during slug generation.

const markdown = `
# <span class="highlight">Important</span> Information
## <code>API</code> Reference  
`;

const result = toc(markdown);
console.log(result.content);
// Output:
// - [Important Information](#important-information)
//   - [API Reference](#api-reference)

// Disable tag stripping
const result2 = toc(markdown, { stripHeadingTags: false });
// Slugs will include HTML tags in processing