cove · crystal · stdlib only

markdown toc that stays honest.

insert, regenerate, or fail ci when it drifts. most toc tools generate once and rot. cove gives you a check you can drop in a workflow, so a stale toc fails the build the same way an un-run formatter does.

$ cove gen README.md       # print toc to stdout
$ cove insert README.md    # update in-place between markers
$ cove check README.md     # exit 1 if toc is stale
$ cove watch README.md     # regenerate on save

how

wrap the block. cove fills it in.

<!-- cove:start -->
- [install](#install)
- [how it works](#how-it-works)
  - [fenced code](#fenced-code)
  - [setext headings](#setext-headings)
- [flags](#flags)
- [ci usage](#ci-usage)
<!-- cove:end -->

# install
## how it works
### fenced code

if markers are missing cove prepends a fresh block at the top. anchors are github-style by default. duplicate slugs get -1, -2 suffixes the way github renders them. fenced blocks are skipped so # comment inside a bash example doesn't pollute the toc.

ci

one line in the workflow.

$ cove check README.md docs/guide.md
README.md: toc is stale (3 headings changed since last insert)
exit 1

fails if anyone edited a heading and forgot to regenerate. that's the whole job.

flags

--depth N: cap heading level. default 6.
--min-headings N: bail silently if the file has fewer. useful for small readmes.
--anchors github|raw: slug style. github is the default; raw keeps punctuation.

install

$ git clone https://github.com/f4rkh4d/cove
$ cd cove
$ shards install
$ crystal build src/cove.cr -o bin/cove --release

written in a weekend. tested on my mac. probably breaks on weird setext edge cases. prs welcome.