Which would you prefer: more options for the TOC extension or a separate "enhanced" TOC extension?

[nevillepark]

Hello all! I've been trying out Yellow and really enjoying it. I've made a version of the Table of Contents extension with some changes, inspired by the useful suggestions and examples in discussion #544.

• Currently, yellow-toc generates an unordered list and uses some code to add numbering. My version allows the user to set whether tables of contents should be ordered (numbered) or unordered, and wraps the list of headings in <ol> or <ul> tags respectively. The same numbering style is achieved with CSS.
• A document may have several levels of headings. Currently, yellow-toc generates a list using only 2 heading levels, with all items at the same level (so no nested lists). My version allows the user to specify the maximum heading level that tables of contents should include, and puts sub-headings in nested lists.

Old style:

<ul>
<li>Heading</li>
<li>Sub-heading</li>
<li>Sub-heading</li>
<li>Heading/li>
</ul>

New style:

<ol>
  <li>Heading</li>
    <ol>
      <li>Sub-heading</li>
      <li>Sub-heading</li>
    </ol>
  <li>Heading</li>
</ol>

@markseuffert asked whether this ought to be its own extension, given that most people may not need the extra options.

I think the changes should be implemented in the main extension because 1) properly marked-up and nested lists are better for accessibility, and 2) it is more elegant and efficient to use <ol> for numbered lists.

Here is my proposal: make it so the default settings and styling create the same result as the previous version. (So, headings up to <h3>, numbered lists with nested numbers for sub-headings, no indentation.) This way, updating the extension won't change the way existing tables of contents look, and users will get the same results "out of the box". However, if they want unordered lists or more layers of sub-headings, they can change the default settings. They can also easily change the presentation (adding indents, changing the numbering or bullet style, etc.) by editing the separate CSS stylesheet.

I would like to hear other people's thoughts on this!

P. S. I am not a programmer, and my code undoubtedly needs editing first—I forgot to take out extraneous comments and it can probably be written more succinctly/correctly. I hope you can understand the methods used from my code.

[annaesvensson]

Hello Neville. I agree that the limitation to level 2 headings can be confusing, it's not obvious to new users why the table of contents shows a coarser level of headings while the document itself has a finer level of headings. Somewhere there is a line between features that everyone needs and features that are rarely used. With multiple extensions we may be able to strike a balance between simplicity and usefulness. I suggest to make a basic toc extension with all levels of headings and an enhanced toc extension for additional features.

[nevillepark]

Sounds good! I'll close my pull request and make a new one that is more pared down.

[markseuffert]

Thanks. Can you update the link to your extension at the top of the discussion?

[markseuffert]

I updated the toc extension for you, now it supports all levels of headings. Hope you like it.

[nevillepark]

Thanks! Is there a reason for generating an unordered list rather than an ordered one?

[markseuffert]

There was no specific reason, I went with the flow and I also didn't want to break existing websites.

[markseuffert]

Oh I didn't mean to say that your complete proposal was implemented, only a small portion which was discussed in #544, but never found its way back into the source code. As you rightly pointed out, the toc extension detected only some headings, HTML elements h2-h3. I updated the source code so that it now detects all levels of headings, HTML elements h2-h6. If someone wonders why the HTML element h1 is always ignored, that's because it's used for the page title. As of today, the toc extension still generates a flattened list with HTML element ul. Sorry for the confusion.