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

Remarkable Plugin

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

Use markdown-toc as a plugin with Remarkable markdown parser instances for integrated TOC generation during markdown rendering.

Capabilities

Plugin Function

Create a Remarkable plugin for TOC generation that integrates with the parser's rendering pipeline.

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

Usage Examples:

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

// Basic plugin usage
function render(str, options) {
  return new Remarkable()
    .use(toc.plugin(options))
    .render(str);
}

const result = render(`
# Overview
Content here.

## Getting Started  
Setup instructions.

## Usage
Usage examples.
`);

console.log(result.content);
// Output:
// - [Overview](#overview)
//   - [Getting Started](#getting-started)
//   - [Usage](#usage)

Plugin Integration

The plugin integrates directly with Remarkable's rendering system.

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

// Create parser instance with TOC plugin
const md = new Remarkable({
  html: true,
  linkify: true
}).use(toc.plugin({
  maxdepth: 3,
  bullets: ['-', '*', '+']
}));

// Render markdown with integrated TOC generation
const markdown = `
# Documentation

## API Reference
API details here.

### Methods
Method documentation.

## Examples
Example usage.
`;

const result = md.render(markdown);
// Returns TOC result object with content, json, highest, tokens

Plugin Options

All standard TOC options are available for the plugin.

interface PluginOptions extends TocOptions {
  /** Exclude first H1 heading (default: true) */
  firsth1?: boolean;
  /** Maximum heading depth to include (default: 6) */
  maxdepth?: number;
  /** Bullet characters for list items */
  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:

const md = new Remarkable()
  .use(toc.plugin({
    maxdepth: 2,
    firsth1: false,
    bullets: '*',
    filter: function(str, ele, arr) {
      return str.indexOf('private') === -1;
    }
  }));

// Custom slugify function
const md2 = new Remarkable()
  .use(toc.plugin({
    slugify: function(str) {
      return str.toLowerCase()
        .replace(/[^\w\s-]/g, '')
        .replace(/\s+/g, '-');
    }
  }));

Renderer Override

The plugin works by overriding Remarkable's renderer to capture heading information.

// The plugin modifies the renderer behavior
const md = new Remarkable()
  .use(toc.plugin());

// During rendering, the plugin:
// 1. Captures all heading tokens
// 2. Processes them for TOC generation  
// 3. Returns structured TOC data instead of HTML

Integration with Other Plugins

The TOC plugin can be combined with other Remarkable plugins.

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

const md = new Remarkable()
  .use(require('remarkable-emoji'))  // Add emoji support
  .use(toc.plugin({                 // Add TOC generation
    maxdepth: 3
  }))
  .use(require('remarkable-attrs')); // Add attribute support

const result = md.render('# Hello :smile:\n## Section {.highlight}');

TOC Comment Processing

The plugin automatically detects and processes TOC comment markers.

const markdown = `
# Introduction
Some content.

<!-- toc -->

## Getting Started
Content here.

## Advanced Usage  
More content.
`;

const md = new Remarkable().use(toc.plugin());
const result = md.render(markdown);

// TOC is generated starting from headings after the <!-- toc --> marker
// Headings before the marker are excluded from TOC

Result Processing

The plugin returns the same result structure as the main TOC function.

const md = new Remarkable().use(toc.plugin());
const result = md.render(markdown);

// Access generated TOC content
console.log(result.content);

// Access structured heading data
console.log(result.json);

// Access metadata
console.log(result.highest); // Highest heading level
console.log(result.tokens);  // Raw Remarkable tokens

Custom Rendering

Use the plugin's structured output for custom TOC rendering.

const md = new Remarkable().use(toc.plugin());
const result = md.render(markdown);

// Custom TOC rendering
const customToc = result.json
  .map(heading => {
    const indent = '  '.repeat(heading.lvl - result.highest);
    return `${indent}${heading.lvl}. [${heading.content}](#${heading.slug})`;
  })
  .join('\n');

console.log(customToc);
// Output numbered list instead of bullets