@muid-io/smart-toc

Smart Table of Contents generator for markdown files with quick stats, exact line numbers and navigation commands

Perfect for AI agents and large documentation files (500+ lines).

⚡ Quick Stats (v3.7.0)

Get instant file analysis without reading the entire document:

# One-line stats (pipe-friendly)
smart-toc document.md --stats --oneline --dry-run
# Output: document.md|fresh|lines(src/toc):847/156|markdown,conf:0.85|h1:3,h2:12,h3:28|/path/document.md.toc

# Human-readable stats
smart-toc document.md --stats --dry-run

# JSON output
smart-toc document.md --stats --json --dry-run

Status values: fresh (up-to-date) | stale (needs refresh) | missing (no TOC) | generated (just created) | refreshed (just updated)

🚀 Quick Start

NPM Installation (Recommended)

# Run directly with npx (no installation)
npx @muid-io/smart-toc document.md

# Or install globally
npm install -g @muid-io/smart-toc

# Then use anywhere
stoc document.md
# or
smart-toc document.md

Python Installation (Alternative)

# Download the script
curl -O https://registry.npmjs.org/@muid-io/smart-toc/-/smart-toc-2.7.0.tgz
tar -xzf smart-toc-2.7.0.tgz
cd package/bin/

# Run directly
python3 smart-toc.py document.md

📖 Usage

Default: Generate .toc File

stoc document.md
# Creates: document.toc (separate navigation file)

Output includes:

• Exact line numbers for every section
• grep/sed commands for instant navigation
• Structure statistics
• AI agent usage instructions

Insert TOC into Original File

stoc document.md --insert-toc
# Modifies document.md (creates backup first)

Quick Stats Mode (v3.7.0)

# Stats + auto-refresh TOC (default behavior)
stoc document.md --stats

# Stats only, no TOC generation
stoc document.md --stats --dry-run

# JSON output (for programmatic use)
stoc document.md --stats --json

# Pipe-friendly single line
stoc document.md --stats --oneline

# Custom header depth
stoc document.md --stats -d 4

Oneline format: filename|status|lines(src/toc):N/N|format,conf:X.XX|h1:N,h2:N|toc_path

Advanced Options

# Control header depth
stoc document.md --max-header-depth 4

# With buffer zone (for frequently updated docs)
stoc document.md --insert-toc --buffer --buffer-size 30

# Custom output path
stoc document.md -o custom-toc.md

# Auto-create TOC section if missing
stoc document.md --insert-toc --auto-create

# See all options
stoc --help

🤖 For AI Agents

Recommended Workflow (v3.7.0)

1. Get quick stats first (don't read entire file):

   stoc document.md --stats --oneline --dry-run
   # → document.md|fresh|lines(src/toc):847/156|markdown,conf:0.85|h1:3,h2:12|/path/document.md.toc

2. Check status: If fresh → read TOC. If stale/missing → run without --dry-run

3. Read the .toc file for navigation table

4. Use line numbers to jump directly:

   Read(file="document.md", offset=458, limit=100)

5. Use search commands from TOC:

   grep -n "SECTION_START: Configuration" -A 75

Benefits

• ✅ 10x faster document navigation
• ✅ 90% token savings (no full file reads)
• ✅ 100% accurate line numbers
• ⚡ Instant section lookup

📋 Requirements

• Node.js: 14.0.0 or higher (for npm package)
• Python: 3.6 or higher (automatically detected)

Both are required for the npm package to work.

📊 Features

What It Generates

## 📑 CURRENT DOCUMENT TABLE OF CONTENTS

### Navigation Table
| Section/Header          | Line(s) | Description | Search Command |
|-------------------------|---------|-------------|----------------|
| Configuration           | 45-120  | Setup info  | `grep -n ...` |
| ├── Database Settings   | 58      | DB config   | `grep -n ...` |
| API Reference           | 125-250 | API docs    | `sed -n ...`  |

Key Features

• ✅ Parses SECTION markers and markdown headers
• ✅ Generates exact line numbers
• ✅ Creates navigation commands (grep/sed)
• ✅ Shows document structure at a glance
• ✅ Verbose output with statistics
• ✅ Automatic backups (with --insert-toc)
• ✅ Buffer zones for TOC growth
• ✅ No external dependencies (Python stdlib only)

🎯 When to Use

Use Default .toc Mode When:

• ✅ Want to review structure without modifying original
• ✅ Need quick AI agent reference
• ✅ Document structure might change
• ✅ Want to keep TOC and document separate

Use --insert-toc Mode When:

• ✅ Document needs to be self-contained
• ✅ Publishing/sharing documentation
• ✅ TOC should be part of version control
• ✅ Using buffer zones for frequent updates

📚 Documentation

Full documentation available in the docs/ directory:

• README_ANALYZER_V2.7.md - Complete guide
• CHANGELOG.md - Version history
• PORTABLE_PACKAGE_GUIDE.md - Portable usage

🔧 Development

Local Testing

git clone <repo>
cd smart-toc
npm link
stoc --help

Publishing (for maintainers)

# Set up auth (one time)
npm config set //registry.npmjs.org/:_authToken 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

# Publish
npm publish --access public

# Update version
npm version patch  # or minor/major
npm publish

📝 Examples

Example 1: Large Documentation

# Generate TOC for large file
stoc ARCHITECTURE.md

# Review structure
cat ARCHITECTURE.toc

# If satisfied, insert into original
stoc ARCHITECTURE.md --insert-toc

Example 2: API Documentation

# With custom header depth
stoc API_DOCS.md --max-header-depth 5

# Creates detailed TOC with deeper nesting

Example 3: Frequently Updated Docs

# Use buffer zone to prevent line shift issues
stoc CHANGELOG.md --insert-toc --buffer --buffer-size 50

🐛 Troubleshooting

Python Not Found

# Install Python 3
# Ubuntu/Debian:
sudo apt install python3

# macOS:
brew install python3

# Windows:
# Download from https://www.python.org/

Permission Denied

# Make script executable
chmod +x node_modules/@muid-io/smart-toc/bin/*.py

Module Not Found

# Reinstall package
npm uninstall -g @muid-io/smart-toc
npm install -g @muid-io/smart-toc

📦 Package Contents

@muid-io/smart-toc/
├── index.js                        # Node.js wrapper
├── bin/
│   └── smart-toc.py  # Python script
├── docs/
│   ├── README_ANALYZER_V2.7.md
│   ├── CHANGELOG.md
│   └── PORTABLE_PACKAGE_GUIDE.md
├── package.json
└── README.md

🔗 Links

• NPM Package: https://www.npmjs.com/package/@muid-io/smart-toc
• Organization: https://www.npmjs.com/org/muid-io
• Issues: https://github.com/muid-io/smart-toc/issues

📄 License

MIT License - see LICENSE file for details

👥 Author

LifeAiTools - Universal TOC parser/analyzer for AI needs Maintained by: @muid-io

🙏 Acknowledgments

• Built for AI agents and large documentation
• Optimized for Claude Code and similar tools
• Part of the muid.io toolkit

Version: 3.7.0 Last Updated: January 15, 2026 Status: ✅ Production Ready