Table of Contents jQuery Plugin

Version 0.8
Written by Doug Neiner
Open Sourced under the MIT License

Based on code and concept by Janko Jovanovic in his article: Automatically generate table of contents using jQuery .

This plugin creates a table of contents based on the <h1> through <h6> tags of a webpage, or subset of a webpage. It auto generates slug-like id’s for linking if they are not present already, can optionally add “Top” links to each heading, offers the choice of nested <ol> or <li> lists or straight <a> links, and can optionally create a proportionate display based on the positioning of the headings.

Examples

• Example 1: Standard TOC, Default Options, Bulleted List
• Example 2: H2 through H4, With Top Links, Scoped to div#wrapper, Ordered List
• Example 3: Proportionate Spacing, H1 through H4

Features

• Can be scoped to any area of the page
• Automatically determines list type based on the container DOM element for the Table of Contents
• Supports nested ordered and unordered lists, as well as a straight listing of links
• Auto-creates slug-like anchors for each heading (on headings that do not already have an id)
• Supports a proportionateSpacing formatting option to create visual TOC that represent actual amounts of content
• Is fully customizable. No CSS classes or ID’s hard-coded into the plugin.
• Supports multiple instances on one page.

Future Feature Ideas

• A popup preview that shows the first few lines of the content following the heading you hover over.
• Built-in support for the jQuery smooth scrolling anchor plugin (This plugin does nothing to hinder a smooth scrolling anchor plugin’s use, it simply does not offer the functionality out of the box).

Basic Usage

Include the jQuery library and the Table of Contents Plugin

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
<script src="jquery.tableofcontents.min.js" type="text/javascript" charset="utf-8"></script>

And call the plugin on an empty container element:

<script type="text/javascript" charset="utf-8">
	$(document).ready(function(){
		$("div#toc").tableOfContents();
	})
</script>

The container element determines the type of list that is displayed. A <ol> container will produce a nested ordered list. A <ul> container will produce a nested bulleted list. Any other container will produce a straight list of links, no nesting.

You cannot use ul or <ol> containers in combination with the proportionateSpacing option.

Advanced Usage Options

The tableOfContents method takes two parameters:

$("#table-of-contents-container").tableOfContents(scope, options)

scope (default: document.body)

If provided, the scope must be a valid jQuery selector (as a string), jQuery collection object, or null. If scope isn’t null or undefined, it will limit the searching of the plugin to only that object and its children. If scope is null or undefined, then it defaults to document.body.

options (name: default)

The following are the options that can accompany the function call:

$("#toc").tableOfContents(null, { optionName: "optionValue" } );

or can be set ahead of time by changing the defaultOptions object:

$.TableOfContents.defaultOptions.optionName = "optionValue";

• startLevel: 1
• depth: 3
startLevel and depth work together to create a range for the Table of Contents. startLevel sets the lowest H tag that should be included. If you wanted your root elements to be all the <h2> tags, you would set this option to 2. depth sets how deep you want your Table of Contents to be, including the startLevel. If you wanted to have your root elements be the <h2> tags, and wanted to also show <h3>, <h4> and <h5> tags, you would set startLevel to 2 and depth to 4.
• levelClass: "toc-depth-%"
  If your Table of Contents container is not a <ol> or a <ul>, then a special class is applied to each link, specifying its depth in relation to the startLevel. First level = 1, second level = 2, etc. You can change this setting, but be sure to include the % sign as it is replaced with the actual depth before being applied to the link.
• levelText: "%"
  Use this setting to add extra text or HTML elements inside each link in the TOC. Be sure to include the % as it will be replaced with the text of the H tag it links to.
• topLinks: false
  This plugin can place “Top” links inside each H tag within its scope by setting this option to true or to the text/html you want it to display. If set to true it defaults to using the word “Top” as the text for the link.
• topLinkClass: toc-top-link
  If topLinks is enabled, this is the class that will be applied to each top link added to the page.
• topBodyId: toc-top
  If topLinks is enabled, each top link will try to link to the id of the body element. If no id is present, this id will be applied to the body element.
• proportionateSpacing: false
  This is a very special feature, directly inspired by Janko’s article and code examples. If you want there to be a certain amount of spacing between each TOC link in direct proportion to the amount of vertical space between each real heading, then set this option to true. If you set this to true you cannot use <ul> or <ol> as your container. Your container cannot have the CSS position of static. It must “haveLayout” by using the position value of fixed, absolute or relative. Finally, your container must have a fixed height.