Allow users to add a Table of Contents to an issue

Problem to solve

Today, issues can become quite long and information dense, with many different sections, dozens of to-dos, cod blocks, and multiple other pieces of information. This can make it difficult for a reader to quickly find what they are looking for, even if a document has been properly marked up with the appropriate Markdown header levels (H1, H2, etc)

Intended users

This is intended to be added by any user writing an issue that will be longer than a few paragraphs and will benefit all readers of that issue.

Further details

Proposal

Allow customers to include a special Markdown tag, such as %TOC%, in their pages. When the page is rendered, this %TOC% text should be replaced by a table of contents section, with each header level indented, as appropriate (no indent for H1, 1 indent for H2, etc)

This could be performed by client-side Javascript to offload need for server computation, if the library needed to do the rendering wouldn't slow the page download significantly.

Permissions and Security

All users able to view the issue should be able to view the rendered TOC blocks.

Documentation

Documentation should be updated to indicate what the supported Markdown tag is and with a few examples of what it looks like.

Testing

What does success look like, and how can we measure that?

We measure success by looking at how many issues have a TOC included or not. We should first look specifically at longer issues (perhaps start with over 200 lines of text?) and look at how many of those issues have adopted the use of TOCs.

Links / references