Documentation

eMI TOC Generator is a simple cross-platform library that dynamically generates a table of contents (TOC) in an HTML 5 page on rendering. The library traverses a page from a specified starting position to its end and inserts a TOC at the starting position. Level one headings (h1) are ignored as it is recommended that only a single level one heading be present in a page and a TOC should not appear before the first and only level one heading. By convention, a TOC is placed after the top level heading and introductory paragraph of a page.

eMI TOC Generator by eMedia Intellect is licensed under GNU General Public License version 3.

Release history

Version	Release date	Notes
1.0	9 February 2016	Initial release.
1.1	30 March 2016	Added automatic heading numbering. Improved heading representation in fragment identifiers. The function encodeURIComponent is used.
1.2	3 June 2016	Added `data-location` attribute to make location more flexible.
1.3	22 June 2016	Added `data-numbering` attribute to make automatic heading numbering optional.
1.4	10 July 2016	Added intentional script termination for when no headings are defined in HTML but TOC script is included. Fixed intentional script termination for when no TOC is defined in HTML but TOC script is included. Replaced `var` keyword with `let` keyword to conform to ES6.
2.0	13 January 2017	Added `data-display-toggle` attribute to allow for display toggling of TOC. Added `data-language` attribute to allow for localisation of TOC. Implemented Web Storage for display toggle state. Renamed `data-location` attribute to `data-relocation`. Renamed `data-position` attribute to `data-float-right`.
3.0	8 March 2019	Added `data-level-restriction` attribute to allow for heading level restriction of TOC. Improved heading representation in fragment identifiers. An underscore and a number is appended to recurring headings for uniqueness. Replaced `window.onload = function() { … };` with `window.addEventListener("load", function() { … }, false);`.
3.1	23 February 2021	Added `@media` CSS for print.

Examples

The following demonstrates how the library can be included in an HTML page:

<!DOCTYPE html>
<html dir="ltr" lang="en-GB">
	<head>
		<meta charset="UTF-8"/>
		<link href="eMI-TOC-Library/Library/TableOfContents.css" media="all" rel="stylesheet" type="text/css"/>
		<script async="async" charset="UTF-8" src="eMI-TOC-Library/Library/TableOfContents.es" type="application/ecmascript"></script>
		<title>Example</title>
	</head>
	<body>
	</body>
</html>

The style sheet applies a minimalist style to the TOC.

The following demonstrates how the TOC can be displayed:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

A div element with the identifier TableOfContents is placed where the TOC is intended to appear.

Numbering

The following demonstrates how automatic heading numbering can be applied:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-numbering="true" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

Display toggle

The following demonstrates how a display toggle can be included:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-display-toggle="true" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

The state of the display toggle is stored using Web Storage.

Float right

The following demonstrates how a right-floated TOC can be displayed:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-float-right="true" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

The style of the TOC is appropriately modified for right-floating.

Relocation

The following demonstrates how the TOC can be displayed in any location:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-relocation="TOCLocation" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
		<div id="TOCLocation"></div>
	</body>

The TOC is populated as if it were in its original location in the DOM.

Localisation

The following demonstrates how the TOC language can be changed:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-language="is" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

The TOC is available in English (default), Icelandic and Spanish.

Level restriction

The following demonstrates how the TOC can be restricted to heading levels above and including heading level 3:

	<body>
		<h1>Top level heading</h1>
		<p>Introductory paragraph</p>
		<div data-level-restriction="3" id="TableOfContents"></div>
		<h2>Level 2 heading</h2>
		<h3>Level 3 heading</h3>
		<h4>Level 4 heading</h4>
		<h5>Level 5 heading</h5>
		<h6>Level 6 heading</h6>
	</body>

The TOC can be restricted to the heading levels 2–5. Restricting the TOC to heading level 1 is invalid. Heading level 6 is the default.