Don't bother with Table of Contents anymore.

updated ...at some nice evening of December 19 :) (7:52 ᴘ.ᴍ.):
...a reference to a more detailed how-to included.

If You write blog posts or articles and publish them on a website, You may consider incorporating Table of Contents. It allows Your Readers to quickly orientate on the content they are about to read (this luxury may be highly appreciated). Furthermore, it provides a way of easy navigating through particular parts of Your work, thanks to which one may quickly jump to the part of their interest right off the bat. Last but not least, it nicely supports and encourages the habit of clarity within the content.

Quick survey on what's coming:

1. How does it work in general?
2. How does it work under the hood?
3. A closer look on the code.

Being a writer, however, the HTML code needed to create such a Table of Contents is not necessarily something You'd be happy to play with. You would rather prefer to stay focused on the actual work (the text), which already puts enough on Your plate.

On the other hand Table of Contents with all its advantages mentioned above seems to be tempting and, what's more important, could make a significant difference from Your Audience perspective.

Fortunately, it doesn't have to be an extra amount of bothering work to handle. Thanks to jQuery You can have Your cake and eat it - simultaneously :) . The only thing You need is to incorporate a simple script under the hood - and You're good to go: keep writing, and Table of Contents will take care on itself pretty well :) .

Here is

how does it work in general.

The idea is simple: the only thing You need is to equip Your article with 1) Table of Contents and 2) headers to which its items refer.

Table of Contents.

A simple numbered list will do :) . You can put it anywhere within Your article, although the most appropriate place seems to be somewhere on the beginning for it to be easily accessible to Your Readers, i.e. without a need to scroll down throughout the page to find it out.

One important thing is a Table of Contents' own header, i.e. a text indicating its role (something like ordinary "Table of Contents" or "Quick summary", etc.). Choose it wisely and then stick to it, because the whole jQuery mechanism will use this to determine is a particular numbered list a Table of Contents, or not necessarily.

Headers throughout article's text.

All Table of Contents items should render Your article's "flow of logic": its main consecutive parts, which should give Your Readers an idea of what they may expect out of it ("the big picture" = what is all about, what its main parts are about).

Once You gave a point to all the main aspects of Your article in a form of a complete Table of Contents - copy each and every ToC item and paste it in the proper places throughout Your article. If You just begin to work on it, just place all the items, one under another, and make some space between then for further fulfillment. Such a "grid" will help You to stay on track while working on the article.

One important thing here is to turn those items into headers. The most appropriate (as far as publishing on the Web is concerned) is to use first-level header as Your article title - while ToC-related headers should stay right next in hierarchy, i.e. taking the form of second-level headers. Whatever You choose, take care that all the ToC-related headers should be of the same type - so if You choose them to be second-level headers, pay attention that all of those will in fact be of this type, not any other.

If You'd like to incorporate more headers than within Your Table of Contents, i.e. more specific ones, say, third-level - feel free to do so, just remember to use appropriate header type, i.e. anything other than the one meant for Table of Contents.

If You write in Markdown, You probably know how awesome and simple are those things there: ## ........ marks a second-level header, ### ..... marks a third-level header, and so on.

How does it work under the hood?

The whole mechanism is based on the HTML approach to the Table of Contents, in which You can easily create such a thing, simply using hyperlinks leading to so-called anchors. Since the trick is meant to do all of this behind-the-scene stuff for You, You don't need to bother Yourself with the code while writing an article.

Here is how does the script work in details:

1. Check if a numbered list within a currently displayed article is in fact a Table of Contents.
2. If so, make each of its items a hyperlink.
3. Put an anchor next to each ToC-related header (throughout the article).
4. Ascribe proper consecutive numbers to all the ToC items.
5. Ascribe proper consecutive numbers to all the ToC-related headers.

Technically-speaking, the whole mechanism wraps the first numbered list's (the one titled in a particular way) items with hyperlinks leading to the proper anchors (which are also automatically created just next to h2 article headers).

Now

a closer look on the code.

Let's investigate this in a step-by-step manner, and then look at the complete final result.

First of all, ensure that You're dealing with a genuine Table of Contents instead of any other numbered list You could use. For the simplicity purposes let's assume that You always put the Table of Contents on the beginning of Your articles. If You, however, would like to be able to put other numbered list(s) before the ToC - I recommend You to read this how-to once You've done here - it is focused exactly on such a case.

In its basic form, the script checks if there is a particular phrase present within the text - the phrase You've chosen as the Table of Contents' title. In My case the phrase is Quick survey on what's coming:

if ($(".post-body:contains('Quick survey on what's coming')").length > 0) {

If a numbered list is really Your Table of Contents, let's do the trick :) . First, wrap each of its items with empty (leading nowhere - You'll handle it soon) hyperlinks with ToC class ascribed.

$(".post-body ol:first li").wrapInner("<a href='' class='ToC'></a>")

Curiosity #1: first next to ol means that the mechanism should be applied only to the first numbered list present within an article. This way it won't confuse it with any other numbered list which You might need to place within the same text.

Curiosity #2: wrapInner wraps everything which is placed between li tags - instead of a sole wrap, which includes those tags in wrapping, therefore lowering the semantics of the code (the only thing wrapped with a hyperlink should be the hyperlink's text to display, not a numbered list's item's HTML tag).

Then put an empty anchor just before each and every second-level header within Your article (remember to carefully choose which headers should be related to Your Table of Contents). Furthermore, as in the previous case, ascribe a (h2) class to those anchors:

$(".post-body h2").before("<a name='' class='h2'></a>")

The reason we use empty hyperlinks and anchors is that in a moment we will fill all of them with proper consecutive numbers, so each Table of Contents' item will be related to the proper in-article header. As a result, when Your Reader click a ToC item, it will lead them to the right place within the article, i.e. where the related header is placed (thanks to the anchor put just next to it).

So let's do the counting :) . First, ascribe proper consecutive numbers to Table of Contents' items:

var cloneCount = 1;
$('a.ToC').each(function() {
$(this).attr('href', '#' + cloneCount)
cloneCount ++;
});

Now You can see why ToC class comes in handy :) . The same is in case of h2 class present here:

var cloneCount = 1;
$('a.h2').each(function() {
$(this).attr('name', cloneCount)
cloneCount ++;
});

But what exactly those two code snippets above do? The first snippet takes a closer look on ToC-classed hyperlinks (i.e. those which make out Your Table of Contents) and fill their address with a # character + the proper consecutive number. So however much ToC items You have, each and every item will be leading just to an anchor named by a simple number (#1, #2, #3, and so on - those are numbered by the second code snippet). As You might know, this is a special way of hyperlinking, which You use whenever You want to lead to some place within the current document. In such a case, instead of providing a full target address (like https://www.somesite.com), a sole #1 will be sufficient. The last needed part of equation here is, however, the accordingly-named anchors placed throughout Your article, signifying its fragments to which their are referring.

Now, here You are the complete final code:

/* *Table of Contents* - start */

if ($(".post-body:contains('Quick survey on what's coming')").length > 0) {

	$(".post-body ol:first li").wrapInner("<a href='' class='ToC'></a>")

	$(".post-body h2").before("<a name='' class='h2'></a>")

	var cloneCount = 1;
	$('a.ToC').each(function() {
	$(this).attr('href', '#' + cloneCount)
	cloneCount ++;
	});

	var cloneCount = 1;
	$('a.h2').each(function() {
	$(this).attr('name', cloneCount)
	cloneCount ++;
	});

}

/* *Table of Contents* - end */