Design Proposal: Table of Contents for documents

[janpio]

Example: https://docs.fastlane.tools/plugins/create-plugin/

Right now it is very hard to get an overview of the content of a document, which is why other documents like https://docs.fastlane.tools/advanced/ use the headline levels to push entries into the navigation on the left (which has its own problems: #455)

For the create-plugin document it would be a better idea to start the document with an auto generated Table of Contents display above the actual content.

This would also work for other documents, but probably not for all of them, which means there would have to be a way to configure this.

[janpio]

One way to do this for pages hosted on Github Pages it using kramdown's {:toc} manually in documents where a TOC is wanted: https://kramdown.gettalong.org/converter/html.html#toc

Update: Oh, this really is only hosted on GH Pages and not generated with Jekyll. So no {:toc} :/

[janpio]

This seems to be in use here: https://pythonhosted.org/Markdown/extensions/toc.html#syntax

[janpio]

Random example:

TOC shows that there are problems with the headlines: "Credentials" is a bit unrelated to all the other stuff and could be place under a "Technical information" (or similar) headline, beginning with "3 examples" - those are a whole different section of the page.