How can I automatically create a table of contents for my index.md files?

[ghost]

Hello everyone!

I have been trying to solve this problem following the advice given in this forum (mkdocs/mkdocs#466), but so far nothing has worked. In my index.md file, I have tried adding [TOC] as suggested, but it hasn't helped. Is there a quick solution to this issue that I can try?

Thanks!

[alexvoss]

I assume you are talking about a TOC for the current page? That is implemented in the Table of Contents Extension or Python Markdown, which you would need to turn on in your mkdocs.yml:

markdown_extensions:
  - toc

Once this is done, the [TOC] placeholder should be replaced with a table of contents.

[ghost]

Thank you for your response! I am very grateful for your assistance.

It turns out that I had asked the question in a way that was incorrect. I wanted the automatically-generated navigation on the left-hand side to appear inside index.md. For example (https://www.mkdocs.org/user-guide/)

[alexvoss]

The example you point to is actually using Markdown to statically define that navigation.

Automatically adding this to your pages might require a bit of effort in the form of a hook to produce. In the on_page_markdown event you can search the placeholder for the ToC and replace it with a list you generate. You'd have to see if you can access the navigation definition from there somewhere and figure out which part you need to render on each page.

I do wonder, though, what it is you are trying to achieve for your users and if it is worth the effort? One of the nice things about Material is that it handles navigation well. What would be the benefit of augmenting or replacing it?

[ghost]

I'm trying to customize the navigation so that when the website opens, only the main sections are visible, and when users visit the site, the navigation appears in more detail.

[alexvoss]

That is what you get by default when you define sections in your navigation. They are collapsed and only the section the user is in opens. You can also lift the main sections up into tabs and hide the sidebars on your homepage.

It is up to you but I do wonder if configuration as described above is not sufficient. It certainly seems a lot simpler to achieve.

[ghost]

I hadn't considered that. Thank you so much, kind sir. I am really grateful that you are here to help. Have a great day and enjoy yourself!