New Advanced Table of Contents version

[nevillepark]

Hi all, I've updated my Advanced Table of Contents extension.

The main differences between it and @annaesvensson's yellow-toc extension:

• When you specify a numbered list, it produces an HTML ordered list (<ol>) rather than an unordered list (<ul>) with added numbering.
• The list is nested: lower-level headings are sub-lists of higher-level parent headings.

This allows users to customize list numbering and markers with CSS, e. g. if they want to use bullets or letters instead of numbers, use different styles of markers for different levels, etc. Because it is properly semantic HTML, it also means it can be styled without requiring special classes for each level.

Why a rewrite was necessary

When I first made it, I actually was wrong about how HTML lists should be nested! Mine produced lists like this:

<ol>
  <li>List item</li> <!-- ← closing </li> -->
    <ol>
      <li>Sub-list item</li>
    </ol>
</ol>

The right way (which it now does) is

<ol>
  <li>List item
    <ol>
      <li>Sub-list item</li>
    </ol>
  </li> <!-- ← closing </li> -->
</ol>

This works far better for screen readers and text-only browsers, and means the CSS does not need as much customization if the theme has minimal CSS or uses a simple classless stylesheet.

Future things to work on

• People might want to include both numbered and bulleted tables of contents on their sites, so perhaps I could add a way for people to specify what kind of ToC they want, either in the [atoc] shortcode or the page's front matter.
• Because of the way PCRE works, headings with the same titles don't get picked up by the HTML-parsing regex. This could be awkward for content that has repeated heading titles, e. g. "Installation", "Ingredients", etc. Currently you can get around this by adding the headings and unique slugs in HTML rather than Markdown. There are other table of contents generators that can automatically give unique IDs to headings, so I'll have to figure out how they do that.
• It's possible for users to skip heading levels, e. g. going from <h2> to <h4>, and it's not easy to work around this and still have properly nested lists. The way I did it produces unsightly gaps in the table of contents list. I'll see if there's a better way to do this. Some ways that have occurred to me are parsing the Markdown content instead, or creating a nested rather than flat array and somehow pruning empty array levels.

If anyone has tips or suggestions, please let me know!