TOC directive as extension for table of contents

[arwedus]

Description / Summary

Doxygen provides a nice syntax for including a table of contents to a markdown document:

Simply add [TOC] as a placeholder. The table of contents will be autogenerated.

NOTE: In Azure devops, this macro is called [[TOC]]. It would make sense to keep the string configurable.

The resulting rst directive should be .. contents::

Value / benefit

• avoid filling up the diffs with explicit TOC changes (like done by Markdown all-in-one extension for VS Code)
• support table of contents in more than just Sphinx (some markdown files are include here and there).

Implementation details

No response

Tasks to complete

No response

[john-hen]

The Markdown link syntax is already overloaded as it is (as I observed in #402), and [TOC] is a valid link in plain Markdown if a target [TOC]: ... is defined elsewhere in the same document. I don't think it's a good idea to add more ambiguity.

[arwedus]

so your suggestion would be to use contents directive then?