Version 0.8
Written by Doug Neiner
Additional Programming by Alexandre Leray, Tiou Lims, and Dennis Stevense (for Digital Deployment)
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.
- 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
- 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.
- 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).
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.
The tableOfContents
method takes two parameters:
$("#table-of-contents-container").tableOfContents(scope, options)
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
.
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
anddepth
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 to2
.depth
sets how deep you want your Table of Contents to be, including thestartLevel
. If you wanted to have your root elements be the<h2>
tags, and wanted to also show<h3>
,<h4>
and<h5>
tags, you would setstartLevel
to2
anddepth
to4
.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 thestartLevel
. 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 totrue
or to the text/html you want it to display. If set totrue
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 thebody
element. If no id is present, this id will be applied to thebody
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 totrue
. If you set this to true you cannot use<ul>
or<ol>
as your container. Your container cannot have the CSSposition
ofstatic
. It must “haveLayout” by using theposition
value offixed
,absolute
orrelative
. Finally, your container must have a fixed height.