Support a way to generate table of content

[Xenonym]

Tell us about your environment

• MarkBind Version: 1.19.0

We include the markdown-it plugin markdown-it-table-of-contents, which generates a table of contents based on Markdown headings where a [[toc]] tag is placed. For example, here's the Formatting Contents user guide page with a [[toc]] tag:

However, we never seem to have documented this feature. Additionally, it seems that the role of a table of contents is already better served by page navigation menus.

1. Are there any MarkBind sites that use this feature, or potential use cases for this feature? If so, we should document it.
2. If not, do we rely on markdown-it-table-of-contents for any other feature? If not, we should probably remove it.

FYI: markdown-it-table-of-contents was added in 6eca765 on March 7, 2017 😮

[damithc]

Oh? I never used it because I didn't know about it. I don't mind keeping it as it can be useful for printer-friendly versions of a page. Also, the page nav disappears at small screen sizes which means a ToC is not entirely useless. Shall we document it?

[Xenonym]

@damithc some caveats found while testing this feature:

• Since this is a markdown-it plugin, HTML headings will not be included in the TOC as they will not be parsed as Markdown.
• The default settings only include headings level 1 and 2, and are only configurable at markdown-it initalisation, meaning there is no way for the user to specify their own heading level in Markdown. If we want to allow a user the same degree of control over the TOC headings as we do with page nav headings, we may have to build this feature ourselves.

[damithc]

• Since this is a markdown-it plugin, HTML headings will not be included in the TOC as they will not be parsed as Markdown.

I see. Should be fine I guess.

• The default settings only include headings level 1 and 2, and are only configurable at markdown-it initalisation, meaning there is no way for the user to specify their own heading level in Markdown. If we want to allow a user the same degree of control over the TOC headings as we do with page nav headings, we may have to build this feature ourselves.

I guess this will have to do, until we create our own (or fork the current plugin)

But make sure the plugin is compatible with our include feature i.e., it captures headings in the included files too.

[damithc]

A follow up: It looks like the [[toc]] in its current form does not work correctly with include. i.e., If I include a file that contains a [[toc]], the output shown in the host page matches the headings of the host page rather than the original page.

[acjh]

This is because Markdown is rendered later, for efficiency.

[acjh]

I think Markdown is only rendered once per page. Rendering rendered Markdown may have undefined behavior.

[acjh]

I suppose it works with dynamic include?

[damithc]

I suppose it works with dynamic include?

It should work for boilerplate includes because the behavior matches boilerplates (i.e., copy content and then render).

[acjh]

Boilerplate includes can be static or dynamic right?

[damithc]

Boilerplate includes can be static or dynamic right?

No such differentiation as far as the current documentation goes.

1. Default: render content in original location and then copy over
2. Boilerplate: copy over content and then render based on the new location

[[toc]] works in the second way.

I have a vague memory of having dynamic includes but it seems to have fallen through the cracks along the way. I remember trying to use that feature but couldn't get it to work.

[acjh]

Boilerplate includes can be static or dynamic right?

No such differentiation as far as the current documentation goes.

Sorry, I mixed it up with static (preload) and dynamic panels.

1. Default: render content in original location and then copy over
2. Boilerplate: copy over content and then render based on the new location

Should be:

2. Boilerplate: render content based on the included location and then copy over to includer

[damithc]

copy over content and then render based on the new location vs render content based on the included location and then copy over to includer

From the user's PoV, is there a difference? The former is easier for the end-user to understand.

[acjh]

The former is missing "copy over" at the end. Whether or not the user's PoV has an additional "copy over" at the start is of less significance.

[damithc]

I didn't think of it when I was revising the boilerplate documentation but later I realized that a simple way to explain the boilerplate behavior is: it is equivalent to copy-pasting the content as is into the included location and then interpreting it. Whereas, normally the content is interpreted in-place and then the result is copy-pasted into the included location. Is that explanation correct, at least from the users PoV?

[acjh]

Nope. If I remember correctly:

it is equivalent to copy-pasting the content as is from the original location into the included location and then interpreting it in the included location and then the result is copy-pasted into the includer location. Whereas, normally the content is interpreted in-place in the included location and then the result is copy-pasted into the ~included~ includer location.

The "copy-pasting" at the start makes it a boilerplate. The "copy-pasted" at the end makes it an include.

[acjh]

Extracting the common part:

it is equivalent to copy-pasting the content as is from the original location into the included location and then interpreting it {{ 1 }}. Whereas, normally the content is interpreted in-place {{ 1 }}

where {{1}} is:

in the included location and then the result is copy-pasted into the ~included~ includer location.

[damithc]

Got it. I forgot there are three (not two) locations involved in a boilerplate inclusion.

[Xenonym]

If includes don't work, is this still worth documenting? Combined with the earlier caveats of fixed heading levels and Markdown-only, documenting a feature with so many exceptions may end up confusing a user and giving a bad impression of the overall product, which I think outweigh the benefit of having a useful feature.

[damithc]

If includes don't work, is this still worth documenting? Combined with the earlier caveats of fixed heading levels and Markdown-only, documenting a feature with so many exceptions may end up confusing a user and giving a bad impression of the overall product, which I think outweigh the benefit of having a useful feature.

Yes, it has far too many flaws ATM. We can keep it undocumented until we make it play nice with other MarkBind features. In particular, I would like it to be able to generate a ToC of an another page so that I can use it to create site/page maps.

Example: siteMap.md :

<include src="chapter1.md#toc" />
<include src="chapter2.md#toc" />

chapter1.md :

<variable name="toc">
[[toc]]
</span>

[tlylt]

Raising the priority to be high as a table of content could be important for CS2103T tP documentation migration

• when printing UG/DG, page navigation will not be available and hence TOC could be quite useful

[tlylt]

To deal with the include problem, I am thinking of removing the markdown-it-table-of-contents plugin and abstracting the logic of the existing pageNav renderer so that it can be used to generate both a page nav, as well as a TOC.

Syntex wise we can still use "[[toc]]" to indicate the place to put the TOC. The initial implementation will have limited configurations, i.e it follows the levels set for pageNav in terms in headingIndexingLevel.

The main purpose is to create printer-friendly versions of a page.

Any feedback/comments are welcomed.

[ang-zeyu]

a huge plus if we can reuse and generalise the same logic as the <pagenav> component

[Tim-Siu]

Professor Damith remarked in the discussion that he is open to retaining the feature as it could enhance the production of printer-friendly page versions. Given that the capability to print the page-navigation has been successfully implemented (as evidenced by Pull Request #2069), the continued use of markdown-it-table-of-contents seems superfluous.