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 |
|
1.2 | 3 June 2016 |
|
1.3 | 22 June 2016 |
|
1.4 | 10 July 2016 |
|
2.0 | 13 January 2017 |
|
3.0 | 8 March 2019 |
|
3.1 | 23 February 2021 |
|
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.