# 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.