Added support for Table Of Contents (toc), removed (broken) support for anchors

[joostdecock]

This PR adds support for Table of Contents generation, and removes the previous support for anchors.

What's the point

A table of contents (toc) is a commonly requested feature when parsing markdown. There's multiple markdown-it plugins that do this in a variety of ways. However, they all add the toc to the body of the markdown content. This makes the toc available as metadata, so you can do what you like with it in nuxt.

Why I got rid of anchors

There was something in nuxtent in a similar vein, which was triggered by the anchorLevels configuration option. This only added link-anchors to titles. Which is part of the work, in the sense that it allows you to link to those titles by anchor.

Not only is it only a partial solution, it also included some scary regex expressions trying to find anchors.
I feel this module should focus on its core mission and let markdown parsing be handled by other people who focus on that.

Furthermore, this already used the markdown-it-anchor plugin for markdown-it under the hood. We still use that, but now let it do the heavy lifting.

How it works

There's a new configuration option toc which controls this feature. I didn't recycle the anchorLevel configuration option, for I don't think it's right to do a different thing under the same name.

By default, this option is false, and no toc will be generated. If you set it to an integer (1 is a classic choice) it will be passed to the markdown-it-anchor configuration as the level parameter, along with the Nuxtent defaults.

These defaults differ from the markdown-it-anchor defaults, and are as such:

• level : whatever you set in your nuxtent.config.js
• permalink: true => Adds an anchor link element to the title (as on GitHub)
• permalinkClass: nuxtent-toc => CSS class that will be added to the anchor link element
• permalinkSymbol: 🔗 => Text/symbol to use for the link element

If you don't like these options, you can override them by setting the toc config option to an object that holds these, or any of the other options supported by markdown-it-anchor.

Actually, that's not true. You cannot set the callback option, as that is what we use to hook back into nuxtent and add the toc.

An example

Setting the toc option to 1 gives the following result for one of my blog posts (just the toc part of the JSON is shown) :

"toc":{
   "topLevel":2,
   "items":{
      "the-freesewing-origin-story":{
         "level":2,
         "title":"The freesewing origin story",
         "link":"#the-freesewing-origin-story"
      },
      "shout-outs":{
         "level":2,
         "title":"Shout-outs",
         "link":"#shout-outs"
      }
   }
}

As you can see, the toc entry has two children:

• topLevel : Highest level of header we encountered in the markdown page
• items : An object containing all the headers

The items each contain:

• level : Level of the heading (as in, 2 for H2, or 4 for H4)
• title : The header text
• link : The link to the anchor that was generated for the header

The topLevel entry is there for those who want to build a hierarchical toc. Since the title of the post is not part of the body, there's typically no H1. There might not even be an H2, so you can't really predict what the top level of you toc will be. That's where topLevel comes in.

Example HTML markup

Out of the box, your anchors will look like this:

<h2 id="the-freesewing-origin-story">The freesewing origin story <a class="nuxtent-toc" href="#the-freesewing-origin-story" aria-hidden="true">🔗</a></h2>

I know, I'm going to have to write a ton of documentation.

[dimitrieh]

Very interesting! can't wait to check this out when merged! 👍

[joostdecock]

It needs some more work, there's still a few links to iron out.