From Some Wiki

What is generated_toc?

generated_toc.js is a Javascript script that automatically creates a nice clickable table of contents for a webpage, based on the existing h1-h6 tags in the page source. Being automatically generated based on the content of the page, it will always be up to date.

The original home of this script is here, and the original author is Stuart Langridge. All I did was add a few modifications to the script to make it a little nicer.

Feature list

The original script had the following features:

Automatically generates the TOC based on h1-h6 tags in the page source
Configurable lowest heading level for TOC
Allow to exclude specific heading tags from TOC
TOC is "collapsible" using the hide/show TOC links
Remembers the TOC setting with a cookie, so that next time you visit the TOC will be in the last state you left it.
"Skip table of contents" link to scroll past the TOC

Here is the list of changes I have made:

Added list type specification for the TOC, ordered or unordered (configurable).
Add "back to top" links after each heading that is included in the TOC (configurable).
Made default to show the toc rather than hide it, if there's no cookie.
Cosmetic improvements to skip and show/hide links.
Add some more documentation and examples (see further in this page, or comments at top of script).

Limitations

Since the TOC anchors are generated on-the-fly by the script, it is not possible to have a persistent link to a particular section of the page (like "page.html#section"). This is because the anchors are only created after the browser loads the page and runs the script, but browser looks for the anchor before it runs the scripts. If you do link to a generated section, the browser will just take you to the top of the page, just as it would for any non-existing anchor.

Download

Please feel free to download the file from the project git repository and give it a whirl.

Documentation

Installation

To install the script, just stick it in some web-accessible directory, and source it into the page using the "script" tag:

<script type="text/javascript" src="generated_toc.js"></script>

Then, at the point where you want the TOC to appear, put in:

 <div id="generated-toc"></div>

Note that if this div is not present, the actual TOC will not appear, even though you sourced in the javascript.

The default options are quite sensible, but there are some customization options, so if you want to customize the appearance of the TOC, read on.

Configuration

The TOC behavior and appearance is controlled through parameters in the page source.

Control heading levels

The TOC defaults to displaying all headings that are contained within the same element as it itself is contained in. For example, in a page like this:

<div>
 <div>
  <div id="generated-toc"></div>
  <h1>foo</h1>
  <h2>bar</h2>
 </div>
 <h1>quux</h1>
</div>

the "quux" heading will not appear in the TOC. To override this, add class="generate_for_page" to the container, which will process all headings on the page wheresoever they may be.

Further, you can control which subset of the range of headings from h6 to h1 will be included. That is done with classes "generate_from_h1" - "generate_from_h6", and "generate_to_h1" - "generate_to_h6". The default is to include all headings h1-h6 (default values are generate_from = 'h1', and generate_to = 'h6').

For example, the following will only include headings level 2 through level 4:

 <div id="generated-toc" class="generate_from_h2 generate_to_h4"></div>

Exclude a specific heading from the TOC

To exclude a heading from the TOC, add a "no-TOC" class to it. For example:

 <h2 class="no-TOC">This will not show up in the TOC</h2>

A particularly useful place to use this is in specifying a title for your table of contents (since having "Table of Contents" appear inside the actual table of contents is kind of silly). For example, you might like the following:

 <div id="generated-toc">
 <h2 class="no-TOC">Table of Contents</h2>
 </div>

Set the list type

To set the TOC list type (ordered or unordered list), give the div of the TOC a class of "list_type_ul" or "list_type_ol". For example:

 <div id="generated-toc" class="list_type_ul"></div>

Default is ordered list ('ol').

Back-to-top links

To enable or disable "back to top" links in the body, give the div a class of "back_to_top_on" or "back_to_top_off". For example:

 <div id="generated-toc" class="back_to_top_off"></div>

The default is "on" - back to top links will be generated after each heading included in the TOC.

Further notes

To specify multiple classes for the div, separate them with spaces. For example:

 <div id="generated-toc" class="generate_from_h3 generate_for_page list_type_ul"></div>

For conflicting class specifications, the last specified class takes precedence. For example, for the following specification:

 <div id="generated-toc" class="generate_from_h3 generate_from_h2 list_type_ul list_type_ol"></div>

The resulting TOC will be generated from h2, and use ordered list type ('ol').

License

This script is licensed under the MIT license.

Have a question or comment?

Feel free to post questions, comments, bugs, or suggestions for improvement, by posting a message in the discussion page. You can also email me (see source code for address).

Generated toc