24 |
25 |
34 |
35 | {{ content }}
36 |
37 |
40 |
41 |
42 |
43 |
44 |
45 |
46 |
51 |
52 |
53 |
54 |
55 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Table of Contents jQuery Plugin - jquery.toc
2 |
3 | A minimal, tiny jQuery plugin that will generate a table of contents, drawing from headings on the
4 | page.
5 |
6 | The generated TOCs are semantic, nested lists (`ul` or `ol`) with hash-link anchors to the headings.
7 |
8 | ## Usage
9 |
10 | You can [download the latest release](http://ndabas.github.com/toc/assets/jquery.toc.zip), or
11 | install with NPM: `npm install jquery.toc`.
12 |
13 | Include jQuery (>= 1.6) and jquery.toc.js/jquery.toc.min.js on your page. The plugin can then be
14 | used either via HTML5 data attributes, or via the programmatic API. See below for the available
15 | options.
16 |
17 | ### Via data attributes
18 |
19 | Minimal example:
20 |
21 |
22 |
Live Example
23 |
24 |
Table of contents, auto-generated from the content on this page:
25 |
26 |
27 |
28 |
Usage
29 |
30 |
31 | You can download the latest release, or install with
32 | Twitter's Bower:
33 | bower install jquery.toc.
34 |
35 |
36 | Include jQuery (>= 1.6) and jquery.toc.js/jquery.toc.min.js on your page. The plugin can
37 | then be used either via HTML5 data attributes, or via the programmatic API. See below for
38 | the available options.
39 |
40 |
Via data attributes
41 |
42 |
Minimal example:
43 |
44 |
<ul data-toc></ul>
45 |
46 |
With options:
47 |
48 |
<ol data-toc="div.container" data-toc-headings="h2,h3,h4"></ol>
49 |
50 |
Via the JavaScript programmatic API
51 |
52 |
Minimal example:
53 |
54 |
<ul id="toc"></ul>
55 | ...
56 | <script type="text/javascript">
57 | $("#toc").toc();
58 | </script>
59 |
60 |
With options:
61 |
62 |
<ul id="toc"></ul>
63 | ...
64 | <script type="text/javascript">
65 | $("#toc").toc({content: "div.container", headings: "h2,h3,h4"});
66 | </script>
67 |
68 |
Options
69 |
70 |
<ul data-toc="content" data-toc-headings="headings"></ul>
71 |
72 |
$(...).toc({content: "body", headings: "h1,h2,h3"});
73 |
74 |
The plugin has two options:
75 |
76 |
77 | -
78 |
content is a selector where the plugin will look for headings to build up
79 | the TOC. The default value is "body".
80 | -
81 |
headings is a string with a comma-separated list of selectors to be used as
82 | headings, in the order which defines their relative hierarchy level. The default value
83 | of "h1,h2,h3" will select all h1, h2, and
84 | h3 elements to build the TOC, with h1 being a level 1,
85 | h2 a level 2, and so on. You can use any valid list of jQuery selectors;
86 | for example, if you just want h1 tags with a specific class, and no
87 | h3 tags, you could use "h1.title,h2" for this parameter.
88 |
89 |
90 |
91 | In addition, the plugin will create nested lists of the same type (ul or
92 | ol) as the element that it is called on.
93 |
94 |
Automatic ID generation
95 |
96 |
97 | The plugin generates hash-links to the headings on the page, to allow users to jump to the
98 | heading by clicking in the generated table of contents. This feature requires that the
99 | headings have IDs assigned; if they do not, the plugin will generate and assign IDs
100 | automatically.
101 |
102 |
The generated IDs are based on the text inside the headings, and uses two simple rules:
103 |
104 |
105 | -
106 | Space characters are converted to underscores. Multiple spaces are replaced with a
107 | single underscore.
108 | - If the ID already exists, a suffix like "_1", "_2", etc. is tried till we get a unique
109 | ID.
110 |
111 |
112 |
113 | For example, a heading like <h2>Heading 2.1</h2> will get the ID
114 | Heading_2.1.
115 |
116 |
Alternatives
117 |
118 |
119 | If you're looking for a jQuery plugin that does more than just generate a minimal table of
120 | contents, the project wiki lists
121 | some more plugins.
122 |
123 |
License
124 |
125 |
126 | Licensed under the Apache License,
127 | version 2.0.
128 |
129 |
Credits
130 |
131 |
Created by Nikhil Dabas.
132 |