Package toc generates a committed "## Contents" table of contents for a markdown file from its heading tree. Unlike a Claude Code `!command` substitution — which runs only at context-load time in slash-command/SKILL files and never as committed bytes — the output here is real markdown, so it is correct on GitHub, for humans, and for every agent that reads the file raw.

The generated list is a plain-text outline — one `- Heading` line per section, nested by depth, with no `[text](#anchor)` links. It shows a long file's scope at a glance without spending a per-line anchor's worth of tokens on every agent that reads the file, and keeps it from registering as a swarm of intra-file link edges in the graph. The list lives directly under a `## Contents` (or `## Table of Contents`) heading — no HTML-comment markers at all — and Rewrite replaces everything between that heading and the next one, so regeneration is idempotent and touches nothing else.

Index ¶

Constants
func Generate(content string) string
func Rewrite(content string) (out string, changed bool, err error)
type Audit
- func Inspect(content string) Audit

Constants ¶

View Source

const LineThreshold = 100

LineThreshold is the file length (in lines) above which a markdown file is expected to carry a Contents TOC — a partial read of a long file should still reveal its full scope.

Variables ¶

This section is empty.

Functions ¶

func Generate ¶

func Generate(content string) string

Generate returns the markdown list a Contents TOC would hold for content: one plain-text `- Heading` line per heading below the top level, nested by depth. Only ATX headings ("## Foo") count; setext headings (text underlined by === / ---) are ignored, since a `---` divider under a prose line reads as a heading to CommonMark but rarely is one. The document title (a level-1 heading) and any "Contents" heading are omitted. Returns "" when there is nothing to list.

func Rewrite ¶

func Rewrite(content string) (out string, changed bool, err error)

Rewrite returns content with a current Contents TOC. When a Contents heading exists, the list between it and the next heading is replaced; otherwise a new "## Contents" section is created immediately before the first section heading (after the title and any intro), or at the top of a heading-only file. changed reports whether the content differs. It errors when there are no headings to tabulate.

Types ¶

type Audit ¶

type Audit struct {
	Lines    int  // total line count
	Entries  int  // headings a TOC would list (0 = nothing to tabulate)
	HasBlock bool // a Contents / Table of Contents heading is present
	UpToDate bool // the list under that heading matches a freshly generated TOC
}