Table Of Contents Anywhere With TOCMonkey, Firefox And Greasemonkey

After delivering to the WordPress community one of the first and most comprehensive table of contents plugins for WordPress, hackadelic.com extends the content navigation experience to any Internet user regardless of the viewed website via its newest provision: TOCMonkey.

Get TOCMonkey

[toc class=toc-right style=”max-width: auto”]

Introduction

The web is an endless source of reading material. The more important it is for readers to be able to quickly get an overview of a piece of content, to get a “mental map” of it before they decide whether and which parts of it to absorb in more detail. A table of contents is among the basic means to provide that experience to readers, alongside with a convenient navigation facility, especially in longish articles.

Alas, there is still (too) much content out there that does not provide such a facility. My personal “favorite” example are man pages like this. They go on forever while leaving the reader in the dark about what follows down the page.

WordPress bloggers are in the lucky position to have access to tools that automate the task of generating a table of contents (so they have no excuse if they didn’t provide some). But what about the rest of the web? Do we have to just take it when there is no TOC where we would want one?

Luckily, we don’t. Thanks to GreaseMonkey, a great Firefox extension, and TOCMonkey, my new Greasemonkey script, it is possible to experience the benefits of a simple table of contents anywhere.

What Is TOCMonkey

TOCMonkey is a table of contents injection tool. It can automatically create a table of contents for any web page you visit and inject it into the page as if it had been a part of it in the first place.

The technology underneath TOCMonkey is GreaseMonkey. GreaseMonkey is a Firefox extension, so TOCMonkey’s primary target audience are Firefox users (but there seem to be GreaseMonkey variants for Internet Explorer, too). GreaseMonkey can be downloaded from mozilla.org.

TOCMonkey Features

• Automatically adds  a simple, single-level table of contents.1
• Heuristically determines whether to use H1, H2 or H3 tags.
• Can be floating or fixed-position. The default is automatically selected based on the size of the TOC.

Get TOCMonkey

1. If you haven’t already done so, get Firefox.
2. Install GreaseMonkey.
3. After installing GreasMonkey, click here to get TOCMonkey. You will be asked whether to install a GreaseMonkey script. Confirm to complete the installation.

Usage

TOCMonkey is a politely discreet piece of software. It stays in the background until you tell it to come up.

When you are viewing a page where you wish they had a table of contents for you to better navigate, but they haven’t, head to the GreaseMonkey icon on your status bar, right-click on it and find the user script menu, than activate the item TOCMonkey: Add Table Of Contents.2

A small panel will appear at the top-right corner of the page that says “TOC”. The panel is semi-transparent so that any text that it accidentally overlays can still be read.

When you hover the mouse over the panel, it expands to a simple table of contents. The table contains only a single level, which I find much more pleasent for quick navigation than a fully nested index. TOCMonkey tries to make a considered guess about whether to include level 1, level 2 or level 3 headings.

For pages containing 30 headings or less (this probably includes most pages you come accross), the TOC will be floating at a fixed position in the browser window regardless of the scroll position on the page. (Hence the semi-transparency.)

If there are more than 30 headings, the TOC box would become to high to fit into the browser window with today’s common screen resolutions, and the TOC box will be inserted at a fixed position on the page, and will scroll with it, so you can reach the TOC items that exceed the browser window boundaries.3

The TOC display mode (in-page vs. floating) can be changed anytime from GreaseMonkey’s user script menu, by clicking on TOCMonkey: Toggle Floating. (See above screen shot).

Restrictions

TOCMonkey works on some pages better than on others. Because the TOC it creates is driven by the heading tags (H1, H2, H3) found on the page, it may be of less use on pages that use H tags in ways other than chapter titles (for example as tab titles). TOCMonkey cannot recognize the semantics behind these tags4, so they will be unconditionally included in the TOC, which may or may not make sense in a particular context.

Credit

TOCMonkey was partially inspired by my recent discussion with Ted about pro’s and con’s of basing WordPress plugins on JavaScript, partially it’s the result of my recent annoyance with poorly navigable man pages. (The latter was an itch that really tipped the scales finally, I can tell you that.)

Disclaimer

TOCMonkey is free software. It is provided as is, and is to be taken as is. No expressed or implied warranties, no free technical support, no … Well, you know what I mean.

If you find this tool useful, splash out on a cup of coffee for the author. Thank you.

1. Contrast to other alleged solutions, I’ve found that generally a single level TOC works best across different pages. [↩]
2. If you don’t see such an item, you are on a web page where TOCMonkey is deactivated. In GreaseMonkey parlance: The URL you are viewing is excluded. Google, Yahoo! and Wikipedia are excluded out of the box, but you can change that at any time from the GreaseMonkey control pannel. [↩]
3. A bug in Firefox’ auto-scroll handling in fixed-position elements prevents from making the TOC box scrollable. A future TOCMonkey version will probably implement a workaround for this. [↩]
4. but than, neither can any other technical solution of this kind out there [↩]

Comments are closed.