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 headerThe 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.
