toc

A Go package for generating Table of Contents from Markdown files. Can be used both as a library in your Go projects and as a command-line tool.

Features

• 🚀 Pure Go package - Easy to integrate into your projects
• 📝 Markdown parsing - Uses goldmark for accurate parsing
• 🎯 Flexible options - Bulleted or numbered lists, skip headers, limit depth
• 🔧 CLI tool included - Can also be used from command line
• ✅ Well tested - Comprehensive test suite

Installation

As a Go package

go get github.com/felizalde/toc/pkg/toc

As a CLI tool

go install github.com/felizalde/toc@latest

Package Usage

Basic Example

package main

import (
    "fmt"
    "log"

    "github.com/felizalde/toc/pkg/toc"
)

func main() {
    markdown := `# My Document
## Introduction
### Background
## Methods
### Data Collection
## Results
## Conclusion`

    // Generate TOC with default options
    tocString, err := toc.GenerateTOC([]byte(markdown), toc.DefaultOptions())
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(tocString)
    // Output:
    // - [My Document](#my-document)
    //     * [Introduction](#introduction)
    //         * [Background](#background)
    //     * [Methods](#methods)
    //         * [Data Collection](#data-collection)
    //     * [Results](#results)
    //     * [Conclusion](#conclusion)
}

Insert TOC into Markdown

markdown := `# API Guide

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

## Authentication
### API Keys

## Endpoints
### Users`

result, err := toc.InsertTOC([]byte(markdown), toc.DefaultOptions())
if err != nil {
    log.Fatal(err)
}

fmt.Println(string(result))
// The TOC will be inserted between the <!--toc--> markers

Custom Options

options := toc.TOCOptions{
    Bulleted: false, // Use numbered list (1. 2. 3.)
    Skip:     1,     // Skip first header level
    Depth:    4,     // Only include headers up to h4
}

tocString, err := toc.GenerateTOC([]byte(markdown), options)

File Operations

// Generate TOC from file
tocString, err := toc.GenerateTOCFromFile("README.md", toc.DefaultOptions())

// Update TOC in file (reads file, generates TOC, writes back)
err := toc.UpdateTOCInFile("README.md", toc.DefaultOptions())

API Reference

Types

type TOCOptions struct {
    Bulleted bool // true for bullets (*), false for numbers (1.)
    Skip     int  // Skip first N headers (default: 0)
    Depth    int  // Maximum header level 1-6 (default: 6)
}

Functions

// Core function: Generate TOC from markdown content
func GenerateTOC(markdown []byte, options TOCOptions) (string, error)

// Generate and insert TOC into markdown content
func InsertTOC(markdown []byte, options TOCOptions) ([]byte, error)

// Convenience function: Generate TOC from file
func GenerateTOCFromFile(filepath string, options TOCOptions) (string, error)

// Update TOC in file
func UpdateTOCInFile(filepath string, options TOCOptions) error

// Get default options
func DefaultOptions() TOCOptions

Default Options

DefaultOptions() = TOCOptions{
    Bulleted: true,  // Use bulleted list
    Skip:     0,     // Don't skip any headers
    Depth:    6,     // Include all header levels (h1-h6)
}

CLI Usage

The package also provides a command-line interface for backward compatibility:

# Basic usage
toc -p path/to/markdown.md

# Generate numbered list
toc -p README.md --bulleted=false

# Output to stdout instead of updating file
toc -p README.md --append=false

# Skip first header and limit depth
toc -p README.md --skip=1 --depth=3

CLI Options

Usage: toc [options]
Options:
    -p, --path      <path>   Path for the markdown file.                    [REQUIRED]
    -a, --append    <bool>   Append toc after <!--toc-->, or write to stdout. [Default: true]
    -b, --bulleted  <bool>   Write as bulleted, or write as numbered list.     [Default: true]
    -s, --skip      <int>    Skip the first given number of headers.           [Default: 0]
    -d, --depth     <int>    Set maximum heading level to be included.         [Default: 6]
    -h, --help               Show this message and exit.

Add <!--toc--> to your markdown file where you want the Table of Contents to appear. The tool will insert the TOC between <!--toc--> and <!--tocstop--> markers.

How it Works

1. Markdown Parsing: Uses goldmark to convert markdown to HTML
2. Header Extraction: Parses HTML to find header elements (h1-h6) with their IDs
3. TOC Generation: Creates properly indented list with links to headers
4. Insertion: Optionally inserts TOC between <!--toc--> and <!--tocstop--> markers

Examples

Check out the example directory for more usage examples.

Requirements

• Go 1.15 or later
• Uses goldmark for markdown parsing
• Uses golang.org/x/net/html for HTML parsing

License

This project is licensed under the Apache 2.0 License.

Contributing

All kinds of Pull Requests and Feature Requests are welcomed!