MkDocs - how to create Table Of Contents from mkdocs.yml inside index.md

Question

I am looking for a way to automatically include TOC within .md files. This sounds like something trivial and was available in GitBook and other static website generators for ages.

Is there any extension supporting it?

Answer 1

Out-of-the-box, no, MkDocs provides no way to pass any information into the Markdown text of a page. However, that could be possible with a plugin. You can find a list of known plugins here. Unfortunately, it does not appear that any plugins on that list pass the global navigation to the Markdown text of a page. However, the markdownextradata and macros plugins would be a good place to start as they both pass other information to the Markdown text.

For completness, note that MkDocs has both global Navigation and a table of contents. I'm assuming you are speaking of the global navigation as you indicate if should come from index.yml. In contrast, a TOC is page specific. Each page has its own TOC which is the list of headings on that page alone. MkDocs makes use of the TOC extension to Python-Markdown, which includes support for inserting a page-specific TOC into the page. Simply insert the text [TOC] on a line by itself anywhere in the Markdown text and the TOC will be inserted there.