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 Insertion

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

Insert table of contents into existing markdown files using HTML comment markers. This functionality allows for automatic TOC management within markdown documents.

Capabilities

Insert Function

Insert or replace TOC content between HTML comment markers in markdown.

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

Usage Examples:

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

// Basic insertion
const markdown = `
# My Document

<!-- toc -->
<!-- tocstop -->

## Chapter 1
Content for chapter 1.

## Chapter 2  
Content for chapter 2.
`;

const result = toc.insert(markdown);
console.log(result);
// Output:
// # My Document
//
// <!-- toc -->
//
// - [Chapter 1](#chapter-1)
// - [Chapter 2](#chapter-2)
//
// <!-- tocstop -->
//
// ## Chapter 1
// Content for chapter 1.
//
// ## Chapter 2
// Content for chapter 2.

TOC Markers

The insertion system uses HTML comment markers to identify where to place the TOC.

Standard Markers:

 - Opening marker where TOC should be inserted
 - Closing marker (optional, for replacement)

Single Marker Behavior: If only  is present, the TOC is inserted after it.

Dual Marker Behavior:
If both  and  are present, any content between them is replaced with the new TOC.

// Replace existing TOC
const markdown = `
<!-- toc -->
- old toc item 1  
- old toc item 2
<!-- tocstop -->

# New Heading
Content here.
`;

const result = toc.insert(markdown);
// Old TOC content is completely replaced

Configuration Options

Customize insertion behavior and TOC generation.

interface InsertOptions extends TocOptions {
  /** Regex for TOC markers (default: /(?:<!-- toc(?:\s*stop)? -->)/g) */
  regex?: RegExp;
  /** Opening TOC marker (default: '<!-- toc -->\n\n') */
  open?: string;
  /** Closing TOC marker (default: '<!-- tocstop -->') */
  close?: string;
  /** Pre-generated TOC content to use instead of generating */
  toc?: string;
}

Usage Examples with Options:

// Custom markers
const result = toc.insert(markdown, {
  open: '<!-- TABLE OF CONTENTS -->\n',
  close: '<!-- END TOC -->',
  regex: /(?:<!-- TABLE OF CONTENTS(?:\s*END TOC)? -->)/g
});

// Pre-generated TOC content
const customToc = '- [Overview](#overview)\n- [Details](#details)';
const result = toc.insert(markdown, {
  toc: customToc
});

// Combined with TOC generation options
const result = toc.insert(markdown, {
  maxdepth: 2,
  bullets: '-',
  append: '\n_(Auto-generated)_'
});

Front-matter Handling

Automatic preservation of YAML front-matter during insertion.

const markdown = `
---
title: Documentation
layout: page
---

# Introduction

<!-- toc -->
<!-- tocstop -->

## Getting Started
Content here.
`;

const result = toc.insert(markdown);
// Front-matter is preserved at the top of the document
// TOC is generated only from content after front-matter

Error Handling

The insertion function includes validation for marker usage.

// Multiple TOC sections not allowed
const invalidMarkdown = `
<!-- toc -->
<!-- tocstop -->

## Section 1

<!-- toc -->  
<!-- tocstop -->

## Section 2
`;

try {
  toc.insert(invalidMarkdown);
} catch (error) {
  console.log(error.message);
  // "markdown-toc only supports one Table of Contents per file."
}

Integration with File Processing

Common pattern for processing markdown files.

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

// Read file, insert TOC, write back
const filePath = 'README.md';
const content = fs.readFileSync(filePath, 'utf8');
const updated = toc.insert(content, {
  maxdepth: 3,
  bullets: '*'
});
fs.writeFileSync(filePath, updated);

Whitespace Preservation

The insertion function preserves trailing whitespace and newlines from the original document.

const markdown = 'Content here.\n\n<!-- toc -->\n\n## Heading\n\n\n';
const result = toc.insert(markdown);
// Original trailing whitespace is maintained