TocMe is a Gradle plugin which adds a Table of Contents to Markdown documents and keeps it up to date.

This plugin uses the great and powerful flexmark-java.

Table of Contents

• Getting started
  • Add the plugin
  • Prepare the Markdown document
  • Add the tocme specification
  • Run the insertTocs task
• Notes - Multiple TOCs in one document - Putting TOCs in multiple documents - Backups
• Options
  • In the Markdown document itself
  • In Gradle
    • Output files
    • Specifying options
    • Available options
• Changelog
  • 1.9
  • 1.8
  • 1.7
  • 1.6
  • 1.5
  • 1.4
  • 1.3
  • 1.2
  • 1.1
  • 1.0

Getting started

Add the plugin

Add the plugin to your project's build.gradle:

plugins {
  id "com.github.blueboxware.tocme" version "1.9"
}

Prepare the Markdown document

Put the following "markers" in the Markdown document at the location where the TOC should be placed:

<!-- toc -->
<!-- /toc -->

⚠️ Don't remove these markers after the TOC is inserted: they are also used to keep the TOC up to date.

Add the tocme specification

Add the tocme specification to build.gradle. For example, if you want a TOC in the file README.md:

tocme {

    doc(file("README.md"))

}

Run the insertTocs task

Run the insertTocs Gradle task.

This will insert the TOC in the specified document. When you run the insertTocs task again after changing the document, it will update the TOC if necessary (to make updating possible, you should not remove the <!-- toc --> and <!-- /toc --> markers from the document after the TOC is inserted).

To only check if the TOCs are up to date, without making any changes, run the checkTocs task.

Notes

Multiple TOCs in one document

You can put multiple sets of markers in one document. A TOC will be inserted at each of the specified locations. By default, each TOC will only contain the headers appearing after the TOC.

You can use the mode option (see below) to specify that a TOC should also include headers appearing above the TOC, or that a "local" TOC should be created (a local TOC only includes the subheaders of the header under which the TOC marker is placed).

Putting TOCs in multiple documents

Repeat the doc directive and/or use docs:

tocme {

    doc("README.md")
    doc(file("doc/reference.md"))

    docs("doc/intro.md", "doc/notes.md")

}

Backups

Backups of all files which are changed or overwritten by the insertTocs task are created in build/tocme/backups/ before making changes.

Options

In the Markdown document itself

You can put a number of space-separated options in the opening markers in a document:

<!-- toc mode=full style=flat levels=1-4 -->
<!-- /toc -->

The following options are available:

Name	Default	Description
style	hierarchy	The style to use for the TOC. Possible values: hierarchy, flat, reversed (flat in reversed order), increasing (flat, alphabetically sorted) or decreasing (flat, alphabetically reversed sorted).
mode	normal	Determines which headers to include. Possible values: normal (only headers which appear after the TOC), full (include headers appearing before the TOC) or local (only subheaders of the header above the marker).
levels	1-3	Which header levels to include. Examples of possible values: "1-4", "1,2,3,4" (same), "1-2,3-4" (same).
numbered	false	When true: number the headers in the TOC.
bold	true	When true: render the headers in the TOC bold.
plain	false	When true: don't make the headers links to their respective sections.

In Gradle

Output files

Instead of having the TOC put in the input file, you can specify one or more output files. The new documents, with the TOC(s), are written to the specified output files, leaving the input file unchanged:

tocme {

    doc("notes.in.md") {
        output("notes.md")
    }

    doc("README.md") {
        outputs("readme_with_toc.md", "doc/readme.md")
    }

}

Specifying options

In the tocme specification, default options can be specified for all documents:

tocme {

    bold = false
    variant = Kramdown

    doc("README.md")
    doc("notes.md")

}

or for a specific input document:

tocme {

    doc("README.md")

    doc("notes.md") {
        numbered = true
        style = Flat

        output("notes_with_toc.md")
    }

}

or for a specific output file:

tocme {

    doc("notes.src.md") {

        output("notes.md")

        output("doc/notes.md") {
            levels = levels("1-5")
            mode = Local
        }

    }

}

When the same option is specified multiple times with different values, the value specified in the <!-- toc --> marker takes preference, next the one specified for the output file, followed by the value specified for the input file and lastly the value specified as default for the tocme specification.

Available options

The following options can be used in build.gradle:

Name	Type	Default	Description
variant	enum	GitHub	The markdown variant to use when parsing the document and creating the TOC. Possible values: Commonmark, Commonmark26 (Commonmark v0.26), Commonmark27 (v0.27), Commonmark28 (v0.28), Kramdown, Markdown, GitHub, GitHubDoc, GitLab, MultiMarkdown, Pegdown and PegdownStrict.
style	enum	Hierarchy	The style to use for the TOC. Possible values: Hierarchy, Flat, Reversed (flat in reversed order), Increasing (flat, alphabetically sorted) or Decreasing (flat, alphabetically reversed sorted).
mode	enum	Normal	Determines which headers to include. Possible values: Normal (only headers which appear after the TOC), Full (include headers appearing before the TOC) or Local (only subheaders of the header above the marker).
levels	int	[1, 2, 3] (levels 1-3)	A collection of integers specifying the level numbers to include. Use the levels() function to specify a string instead, for example: levels = levels("1,3-5")
numbered	bool	false	When true: number the headers in the TOC.
bold	bool	true	When true: render the headers in the TOC bold.
plain	bool	false	When true: don't make the headers links to their respective sections.

Advanced options

Name	Type	Default	Description
tag	string	"toc"	The keyword to use in the toc-markers in the markdown document.
removeEmojis	bool	false	Remove emojis from the header texts in the TOC.
requireSpace	bool	true	When true: don't recognize headers without a space between the # and the header text (#Header)
dupedDashes	bool	...1	When false: replace duplicate dashes in header link ids with a single dash.
resolveDupes	bool	...1	When true: add a number to duplicate header link ids to make them unique.
dashChars	string	...1	A string specifying the characters to replace with a dash in header link ids.2
allowedChars	string	...1	A string specifying the characters which are allowed in header link ids. Alphanumeric characters are always allowed.2
allowLeadingSpace	bool	...1	When true: allow non-indent spaces before headers.
emptyHeadingWithoutSpace	bool	true	When false: don't recognize empty headers without a space following the '#'.
setextMarkerLength	int	...1	The minimum number of - or = characters to use under a setext header for it to be recognized as header.
headingInterruptsItemParagraph	bool	true	When true: allow headings to interrupt list item paragraphs.

¹: Default depends on the used variant.

²: Non-alphanumeric characters are removed from header links ids, except for the characters specified in dashChars, which are replaced by a dash, and characters in allowedChars, which are not removed or replaced but left as is.

Changelog

1.9

• Compatibility with the Build Cache
• Compatibility with the Configuration Cache
• Use lazy properties for everything

1.8

• Fix AssertionError sometimes being thrown.

1.7

• Compatibility with Gradle's configuration cache: #6.

1.6

• Compatibility with Gradle 8.0: #5.

1.5

• Internal change only: remove usage of ConfigureUtil in preparation for Gradle 8.0.

1.4

• Now uses 3 spaces as indentation instead of 2. Fixes #3: incorrect formatting of nested lists in numbered lists.

1.3

• Compatibility with Gradle 7.1 (#2)

1.2

• Changed the way the included levels are specified in Gradle. The levels parameter now takes a collection of integers.
• Update to Flexmark 0.62.2
• Update to Gradle 6.5.1

1.1

• checkTocs now fails the build if there are out of date TOCS.

1.0

• Initial version