or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md file-utilities.md index.md programmatic-api.md

tile.json

Command-Line Interface

DocToc's command-line interface provides comprehensive markdown TOC generation with extensive configuration options and multi-platform support.

Capabilities

Basic Command Syntax

Process markdown files or directories to generate/update table of contents.

doctoc [mode] [options] <path>

Parameters:

path: File path or directory to process (required)
mode: Platform compatibility mode (optional)
options: Configuration flags (optional)

Platform Modes

Specify target platform for anchor compatibility.

--github    # GitHub-compatible anchors (default)
--gitlab    # GitLab-compatible anchors  
--bitbucket # Bitbucket-compatible anchors
--nodejs    # Node.js documentation style
--ghost     # Ghost publishing platform

Usage Examples:

# GitHub mode (default)
doctoc README.md

# GitLab mode
doctoc --gitlab docs/

# Bitbucket mode for specific file
doctoc --bitbucket CONTRIBUTING.md

Configuration Options

Control TOC generation behavior and output formatting.

--help, -h                 # Show usage information
--title, -t <title>        # Specify custom TOC title
--notitle, -T              # Omit TOC title completely
--maxlevel, -m <level>     # Maximum heading level (1-6)
--entryprefix <prefix>     # Entry prefix character (default: -)
--all                      # Include headers before TOC location
--update-only, -u          # Only update files that already have TOC
--stdout, -s               # Output to stdout instead of modifying files

Usage Examples:

# Custom title and max level
doctoc --title "Contents" --maxlevel 3 docs/

# No title with custom prefix
doctoc --notitle --entryprefix "*" README.md

# Output to stdout for preview
doctoc --stdout README.md

# Only update existing TOCs
doctoc --update-only .

Directory Processing

Process multiple markdown files in directory structures.

# Process current directory recursively
doctoc .

# Process specific directory
doctoc docs/

# Process with options applied to all files
doctoc --maxlevel 4 --all src/docs/

Behavior:

Recursively searches directories for .md and .markdown files
Ignores .git, node_modules, and hidden directories
Processes each found file with the same options
Provides progress feedback for each file processed

TOC Placement Control

Control where TOCs are inserted or updated in markdown files.

Automatic Placement:

Inserts TOC at the beginning of the file if no existing TOC
Uses HTML comment markers to identify TOC sections

Manual Placement: Place HTML comments in your markdown to control TOC location:

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Skip Processing: Add skip tag to prevent TOC generation:

<!-- DOCTOC SKIP -->

Options for TOC Processing:

--all           # Include headers appearing before the TOC location
--update-only   # Only process files that already contain TOC markers

Error Handling

Common error scenarios and solutions.

Invalid Max Level:

doctoc --maxlevel abc README.md
# Error: Max. heading level specified is not a positive number: abc

Unknown Options:

doctoc --invalid-option README.md  
# Error: Unknown option(s): --invalid-option

File Not Found:

doctoc nonexistent.md
# Error: ENOENT: no such file or directory

Output Examples

Default Processing:

$ doctoc README.md

DocToccing single file "README.md" for github.com.

==================

"README.md" will be updated

Everything is OK.

Stdout Output:

$ doctoc --stdout README.md

DocToccing single file "README.md" for github.com.

==================

**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)

==================

"README.md" should be updated

No Changes Needed:

$ doctoc README.md

DocToccing single file "README.md" for github.com.

==================

"README.md" is up to date

Everything is OK.