Table of Contents Extension

flexmark-java Table-of-Contents extension

Overview

Table of contents extension is really two extensions in one: [TOC] element which renders a table of contents and a simulated [TOC]:# element which also renders a table of contents but is also intended for post processors that will append a table of contents after the element. Resulting in a source file with a table of contents element which will render on any markdown processor.

Syntax

The extension has a class for generating the updated text to go under the simulated TOC element.

The TOC tag has the following format: [TOC style]

The simulated TOC tag has the following format: [TOC style]: # "Title"

1. style consists of space separated list of options:

   • levels=levelList where level list is a comma separated list of levels or ranges. Default is to include heading levels 2 and 3. Examples:

     • levels=4 include levels 2,3 and 4
     • levels=2-4 include levels 2,3 and 4. same as levels=4
     • levels=2-4,5 include levels 2,3,4 and 5
     • levels=1,3 include levels 1 and 3

   • html simulated TOC only, generate HTML version of the TOC content

   • markdown simulated TOC only, generate Markdown version of the TOC content

   • text to only include the text of the heading

   • formatted to include text and inline formatting

   • bullet to use a bullet list for the TOC items

   • numbered to use a numbered list for TOC items

   • hierarchy: hierarchical list of headings

   • flat: flat list of headings

   • reversed: flat reversed list of headings

   • increasing: flat, alphabetically increasing by heading text

   • decreasing: flat, alphabetically decreasing by heading text

2. "Title" specifies the text for the table of contents heading. If omitted or blank then no heading will be generated for the table of contents. # prefix in the title will specify the header level to use for the heading above the table of contents listing. If no # prefix is used then the heading level will be taken from SimTocExtension.TITLE_LEVEL option.

The lines after the [TOC]: # tag are intended to be updated to reflect the content of the document. The child node SimTocContent represents the text which is to be replaced with an updated table of contents.

Parsing Details

Use class TocExtension or SimTocExtension in artifact flexmark-ext-toc.

The following options are available:

Defined in TocExtension class:

Static Field	Default Value	Description
LEVELS	0x00C0	bit mask of header levels to include in the TOC, 1 << header_level, use TocOptions.getLevels(int...) and pass in a list of header levels
IS_TEXT_ONLY	false	rendered table of contents only uses the heading element's text, emphasis and other inline processing is ignored.
IS_NUMBERED	false	use ordered lists to generate the list of headings

Defined in SimTocExtension class:

Static Field	Default Value	Description
LEVELS *	0x00C0	bit mask of header levels to include in the TOC, 1 << header_level, use TocOptions.getLevels(int...) and pass in a list of header levels
IS_TEXT_ONLY *	false	rendered table of contents only uses the heading element's text, emphasis and other inline processing is ignored.
IS_NUMBERED *	false	use ordered lists to generate the list of headings
IS_HTML	false	use HTML version of the TOC to generate the Content text, otherwise Markdown (only applies to post processing of the file that you must provide)
TITLE_LEVEL	1	default heading level for the title of the table of contents if one is not specified in the title string with prefixed #'s
TITLE	false	default text for the table of contents title if one is not specified with the element
AST_INCLUDE_OPTIONS	false	include style option defined in the sim TOC element as part of the AST. default style are not included in the ast, style is available in the SimTocBlock

* ⚠️ These keys are references to the keys in the TocExtension. The two sets refer to the same data points in the data set.