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"

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. If a range is specified using - as separator between numeric values then the included range is from first numeric to last numeric inclusive. If first numeric is missing then 1 will be used in its place. If last numeric is missing then 6 will be used in its place.
  
  Examples:
  - levels=1 include level 1 only, same as levels=1,1
  - levels=2 include level 2 only, same as levels=2,2
  - levels=3 include levels 2 and 3
  - 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
  - levels=-3 include levels 1 to 3
  - levels=3- include levels 3 to 6
- 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
"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
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	`""`	default text for the table of contents title if one is not specified with the element
DIV_CLASS	`""`	class attribute to use on table of content `div` wrapper
LIST_CLASS	`""`	class attribute to use on table of content `ul`
AST_INCLUDE_OPTIONS	`false`	include style option defined in the TOC element as part of the AST. default style are not included in the ast, style is available in the TocBlock
CASE_SENSITIVE_TOC_TAG	`true`	setting it to false allows `[TOC]` and `[TOC]: #` to be matched without case sensitivity. The syntax for toc options is still case sensitive.

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 *	`"Table of Contents"`	default text for the table of contents title if one is not specified with the element
DIV_CLASS *	`""`	class attribute to use on table of content `div` wrapper
LIST_CLASS *	`""`	class attribute to use on table of content `ul`
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
CASE_SENSITIVE_TOC_TAG *	`true`	setting it to false allows `[TOC]` and `[TOC]: #` to be matched without case sensitivity. The syntax for toc options is still case sensitive.

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

Custom HTML Attribute Provider

AttributablePart distinguishes individual tags used for rendering the element since the Node cannot be used to distinguish between tags in compound HTML rendering. For example of custom attribute provider refer to AttributeProviderSample2.java

These are defined in TocExtension and for convenience duplicated in SimTocExtension