AutoTOC

Summary: Unobtrusive Automatic Table of Contents links
Version: 20170717
Status: stable
Prerequisites: PmWiki 2.2.56 or newer
Maintainer: Petko
Users: +8 (view / edit)
Discussion: AutoTOC-Talk
License: GPL3+

An Automatic Table of Contents for wiki pages. If JavaScript is enabled in your browser, you should see it below this paragraph.

Description

For an intranet wiki, I needed a really basic, simple and fast Table of contents, that:

  • works in all existing pages without the need to edit them and add some markup,
  • works even when the headings in the page are not in a logical hierarchy,
  • works even when the headings in the page come from included pages or from pagelists,
  • works with the TOC block either in the wiki page, or in the SideBar,
  • can be disabled on some pages,
  • can be moved to a different place in a page,
  • can be shown or hidden by the users and their preferences can be remembered,
  • wouldn't risk to break some complex local recipes on that wiki.

AutoTOC was inspired by the tables of contents in Wikipedia, very simple and with extremely small need for maintenance:

  • a page with less than 3 headings is usually short and doesn't need a TOC
    • it is possible to force a TOC for 1-2 headings with a special markup
    • it is possible to disable the TOC for 3+ headings with a special markup
  • the TOC is automatically inserted right before the first heading in the page and after the short introduction / summary
    • it is possible to place the TOC anywhere in a page with a special markup
  • it is possible to automatically have numbered headers in the page and in the table of contents.

Installation

  • Copy autotoc.phpΔ to your pmwiki/cookbook directory.
  • Copy autotoc.js to your pmwiki/pub directory.
  • Add to config.php such a line:
    if($action=='browse') include_once("$FarmD/cookbook/autotoc.php");

Usage

  • A reader can show or hide the Table of contents with a show/hide link. The TOC state (open or closed) will be remembered when the reader opens another page.
  • A page with 3 or more headings will have the Table of contents inserted right before the first heading.
  • The wiki markup (:toc:) at the beginning of a line places the table of contents there, even if there are less than 3 headings.
  • The directive (:notoc:) disables the Table of contents.
  • To exclude individual headings from the table of contents, apply to them the class "notoc", eg.
    !! Heading not in the TOC %block notoc%
    Note: an element can have more than one class, so if it already has a class name, just add the "notoc" class after a space.
  • To exclude blocks of text from scanning for headings, apply to them the class "notoc", eg.
    >>notoc<< or >>comment notoc<<

The recipe allows more than one TOC block on a single page. This was implemented for a Single-page application but can be used in normal wiki pages. To enable multiple TOC blocks, wrap every section in a <div class='spa_pagecontent'>...</div> element, or with the wiki markup, (:div7 class=spa_pagecontent:).

Configuration

The following variables can be set in config.php before including the recipe:

  • $AutoTocPosition = "wikitext"; Use this variable to override the "default" positioning of the table of contents; default is empty which inserts the table right before the first heading; setting here the id of a div block will insert the table at the top of the block. For example "wikitext" at the top of the main page area, and "wikileft" in most skins will place it at the top of the sidebar.
  • $AutoTocMaxLevel = 3; the levels of the headings included in the Table of Contents; setting 3 will mean !, !! and !!! headings will appear in the TOC; default is 6, ie. ! to !!!!!!.
  • $AutoTocNbHeadings = 4; the minimal number of headings in a page which enable Tables of contents; default is 3 headings, a page with fewer headings than this number will not display a TOC unless it has the (:toc:) markup.
    If you want TOCs appearing not automatically on all pages, but only in pages with the (:toc:) markup, set the $AutoTocNbHeadings variable to -1.
  • $AutoTocIndent = "&nbsp;&nbsp;&nbsp;"; how to indent the links of different levels of headings.
  • $AutoTocPrefix = "&#9632;&nbsp;"; a prefix to a TOC link (default is nothing); here you can set some character that could make the TOC look like a bulleted list, eg. &#9632; is a ■ square, &#8226; is a • circle, &#8227; is a ‣ triangle, &#8259; is a ⁃ dash. See also Numbered headings below.
  • $AutoTocIdEncoding = "default"; the encoding mode which creates anchor names based on the heading text. There are 4 possibilities.
    • The "default" mode encodes spaces to "_", and every character other than [A-Za-z0-9] to its UTF-8 codepoints.
    • The "numeric" mode will create anchors of the form "at_N" where N is a number.
    • The "fold" mode converts the heading to lowercase, replaces all accented Latin letters with their non-accented variants, translates Cyrillic and Greek letters to their Latin variants, encodes spaces to "_", and removes all other characters. Demo.
    • The "acronyms" mode is like the "fold" mode, but it starts with an _underscore character and only keeps the first letter of each word.
  • $AutoTocCustomFold['replace1'] = "/search1/g";
    $AutoTocCustomFold['replace2'] = "/search2/g";
    This array contains strings to be searched and replaced in the "fold" mode. The "replace" part is a string, the "search" part is a JavaScript regular expression. For example, to replace all typographical apostrophes, dashes, tildes with a single dash, you can use this line:
    $AutoTocCustomFold['-'] = "/(~|’|`|'|–|‐|‑|−|﹣|-)+/g";

Numbered headings

AutoTOC can automatically number the headings in the page, as well as in the table of contents. To enable this feature, set to config.php the line:

  $AutoTocPrefix = "#"; 

You can see this feature enabled at the talk page.

Styles and Appearance

The TOC block has the "frame" class which should look consistently in different skins. It is possible to control the appearance of the table of content via styles in the file pmwiki/pub/css/local.css (if it doesn't exist, create it). For example, to remove the border and the background of the table of contents, add this line to local.css:

  .tableTOC { border: none; background: none; }

The CSS elements which can be styled are .AutoTOCdiv (the outer div), .tableTOC (the inserted <table> block), .headerTOC (the "Contents [show/hide]" row) and .innerTOC (the links to the sections). For example, to have non-underlined links in the TOC you could set in local.css one of these lines:

  .tableTOC  a { text-decoration: none; } /* don't underline TOC links -OR- */
  .headerTOC a { text-decoration: none; } /* don't underline show/hide link */

Other example, for a right-aligned floating table of contents (used with $AutoTocPosition = "wikitext";):

  .AutoTOCdiv {float: right;}

Internationalization

International wikis can translate the following strings, eg. in a French XLPage:

  'Contents' => "Sommaire",
  'show' => "afficher",
  'hide' => "masquer",

Notes

  • Your skin needs the standard marker <!--HTMLFooter--> near the bottom of the file, right before </body></html>.
  • The browser of the visitor needs JavaScript to be enabled.
  • Alternative markups for the recipe are (:tdm:), (:notdm:), >>notdm<< for French users (tdm for "table des matières").

Release notes

  • 20170717 : Fix bug when a heading contains some special characters.
  • 20170710 : Remove unneeded debug logs.
  • 20170618 : Update for PHP 7.2 (requires PmWiki 2.2.56 or newer).
  • 20140403 : Rewrite code to encapsulate it in a single object, and to allow TOC blocks in multiple sections of a page. Note that the Styles and appearance configuration changed from using #AutoTOC with a hash to .AutoTOCdiv prefixed by a dot.
  • 20140205a : fix bug when $AutoTocNbHeadings = -1; reuse markup from HandyTableOfContents, SlimTableOfContents and QuickPageTableOfContents for easier migration of existing pages to AutoTOC.
  • 20140205 : update recipe for PHP 5.5; reuse markup from PageTableOfContents for easier migration of existing pages to AutoTOC.
  • 20130114 : $AutoTocPrefix can be set to "#" to enable numbered headings.
  • 20120912 : $AutoTocNbHeadings can be set to -1 to disable ToC without a (:toc:) directive.
  • 20120416 : added $AutoTocCustomFold.
  • 20120415 : added $AutoTocPosition, (no)tdm French markups.
  • 20120202 : minor changes to the "fold" (keep dashes) and "acronyms" (start with underscore) modes.
  • 20120128 : fix scroll when a page#section is called from other pages.
  • 20111222a : added folding for Greek to Latin.
  • 20111222 : added $AutoTocIdEncoding.
  • 20111110 : fixed forced TOC when WikiWords are enabled.
  • 20111025 : added $AutoTocIndent and $AutoTocPrefix.
  • 20111024 : added "notoc" triggers.
  • 20111023 : fix bug with apostrophe, reported by Luigi, and bug when an element with the generated heading ID already exists.
  • 20111022 : refactor/rename all JS functions and global variables to prevent conflicts with other scripts.
  • 20111019 : fix bug with tables, reported by Oliver.
  • 20111018 : headings inside (:markup:) blocks are now skipped from the table of contents.
  • 20111008 : generated anchors changed from numeric incremental to a simple encoding of the heading text, outlined at PITS:00955, for example #Installation.
  • 20111007 : fix HTML validation bug.
  • 20111006 : fix indentation to the lowest common level of headings in the page.
  • 20111005 : added $AutoTocNbHeadings.
  • 20111004 : first public release, ready to be tested.

See also

Cookbook /
Accordion  lightweight Accordion javascript requiring no framework (stable)
HandyTableOfContents  Handy Client-side Table of Contents (stable)
NumberedHeaders  Display numbered headers, indented paragraphs and table of contents (Stable)
NumberedSections  Add section numbers on a page (stable)
PageTableOfContents  Adds a clickable table of contents to a page (Stable)
QuickPageTableOfContents  Adds a dropdown clickable table of contents to a page - client side processing (Stable)
SlimTableOfContents  Simple or Numbered Table of Contents, Compatible with SectionEdit Recipe (not working with php5.5)
TableOfContentsPortion  Inserts a portion of external table of contents into the page (Alpha)

Contributors

  • Recipe written and maintained by Petko (5ko [snail] 5ko [period] fr).
  • If this recipe helps you or saves you time, you can help support its continued development by .

Comments

See discussion at AutoTOC-Talk

Heading not in the table of contents

The heading above has the class "notoc" (with the markup %block notoc%) so it will not appear in the table of contents.

Voilà en français

Testing...

Français

Testing...

Comments

See discussion at AutoTOC-Talk

User notes +8: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.