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.