danger-toc

A plugin for danger.systems that makes sure your project's README.md has a TOC. Requires Ruby 3.1 or newer.

Table of Contents

• Installation
• Usage
  • toc.check!
  • Options
    • files
    • header
    • parser
    • format
    • bullet
    • indent
    • max_depth
    • report
  • Global Defaults
• Contributing
• Copyright

Installation

Add danger-toc to your Gemfile.

gem 'danger-toc'

Add toc.check! to your Dangerfile. Make a pull request and see this plugin in action.

Usage

Methods from this plugin are available in your Dangerfile under the toc namespace. Every option can be set globally or passed to a check. Per-check options override global defaults without changing them.

toc.check!

Check README.md with default options, or pass options for a particular set of files:

toc.check!
toc.check!(files: ['README.md', 'DEV.md'], header: 'Contents')

The method returns whether all checked TOCs are correct and reports every failing file. Use toc.toc_changes?(files: ['README.md']) to detect modified or added files before running a check.

Options

toc.check!(files: ['README.md'], max_depth: 3)
toc.check!(files: ['docs/guide.md'], parser: 'Kramdown', format: :kramdown, bullet: '*', indent: 4)

files

File paths to check. Default: ['README.md'].

toc.check!(files: ['README.md', 'DEV.md'])

header

TOC heading text, without #. Default: 'Table of Contents'.

toc.check!(header: 'Contents')

When a TOC is missing, a leading # Title is excluded if every subsequent heading is nested below it. A lone heading or multiple top-level sections are retained. When a TOC exists, headings before it are excluded.

parser

Kramdown input parser name. Default: 'GFM'. GFM and Kramdown input are available out of the box; install and require additional Kramdown parsers before selecting them.

toc.check!(parser: 'Kramdown')

format

Anchor ID format: :github (default) or :kramdown. This is independent of the input parser.

toc.check!(parser: 'Kramdown', format: :kramdown)

bullet

List marker: '-' (default), '*', or '+'.

toc.check!(bullet: '*')

indent

Non-negative number of spaces per nesting level. Default: 2.

toc.check!(indent: 4)

max_depth

Maximum absolute Markdown heading level (1–6). Default: nil, including all levels. For example, 2 includes # and ## headings but not ###.

toc.check!(max_depth: 2)

report

Report style: :full (default) shows the complete expected TOC. Use :diff to show mismatched entries with two surrounding entries of context. Removed lines are prefixed with -, additions with +. Missing TOCs always show the full suggestion.

toc.check!(report: :diff)

Global Defaults

Set shared defaults on toc, then override individual settings for a particular check:

toc.files = ['README.md', 'DEV.md']
toc.header = 'Contents'
toc.check!
toc.check!(files: ['docs/guide.md'], header: 'Guide Contents', parser: 'Kramdown')
toc.check! # still checks README.md and DEV.md using the Contents header

The same global/per-check choice applies to every option in the table, including report, format, and max_depth. Global settings are shared across plugin instances; each check captures its own immutable configuration snapshot.

Contributing

See CONTRIBUTING.

Copyright

Copyright (c) Daniel Doubrovkine, 2017-2019

MIT License, see LICENSE for details.