How to add an item to the table of contents?

[woter1832]

Hi,

I have enabled Isso comments on my site. For pages that have comments enabled, I would like to include the heading Comments in the table of contents.

For example:

I note the word Comments is rendered as part of MKDocs and not Isso. I also note the heading tag <h2> has no class or id assigned:

The other headings have id="heading-2" (for example). My assumption is that if I could give Comments the id="heading-2" then it would automatically be added to the table of contents, but I haven't been able to work out how to make this modification.

This is the code in ...docs/overrides/partials/comments.html

{% if page.meta.comments %}
  {# Comment system (Isso) #}
  <div id="__comments">
    <script
      data-isso="{{ config.extra.comments_url }}/"
      data-isso-css-url="/stylesheets/isso.css"
      data-isso-require-author="true"
      data-isso-require-email="true"
      data-isso-reply-to-self="false"
      data-isso-vote="true"
      data-isso-reply-notifications-default-enabled="true"
      src="{{ config.extra.comments_url }}/js/embed.min.js">
    </script>
    <hr><section id="isso-thread"><h2>Comments</h2></section>
    <noscript>Please enable JavaScript to view the comments.</noscript>
  </div>
{% endif %}

I'd be grateful if anyone could provide any suggestions.

Thanks in advance.

[woter1832]

Clearly, I was having trouble seeing the wood from the trees! It was right there in the comments.html:

<hr><section id="isso-thread"><h2>Comments</h2></section>

Mine now looks like:

<hr><section id="isso-thread"><h2 id="heading-2">Comments</h2></section>

I've since realised that the ID tag has nothing to do with what is shown in the table of contents. The ID tag is a formatted version of the text. i.e. a heading of This is my demo heading would have an ID tag of id="this-is-my-demo-heading".

Back to the drawing board...

[kamilkrzyskow]

Hello @woter1832,
the TOC is filled out using the toc extension, which is enabled by default by MkDocs. So between on_page_markdown and on_page_content events, the page.toc structure is filled out.

You should be able to modify it using a hook or perhaps directly in your templates before the template code responsible for rendering the toc is executed.🤔

[kamilkrzyskow]

A simple example without conditionals to limit it to the pages with comments, but should be enough to get you 80% there ✌️

from mkdocs.structure.toc import AnchorLink

def on_page_content(html, page, config, files):
    
    if not page.toc or not page.toc.items:
        return
        
    page.toc.items[0].children.append(AnchorLink("Comments", "comments", 2))

EDIT:
Apart of the default suggestion to use a comments true/false flag in the meta header and your addition below, there are also other conditionals you could want to use. Like the page.file.src_uri.startswith("blog/posts") which would include every post in the directory, or another option is page.meta.template == "blog-post.html" to include every page which uses the blog-post template, which is useful when you're using multiple blog instances.

EDIT2:
While page.meta.template or page.meta.comments works in the templates, in Python dicts are accessed using dict[key] or dict.get(key) where the former crashes in case of missing key and the latter returns None. So the approach below is correct.

[woter1832]

Thank you @kamilkrzyskow.
That has worked.

I'll have to try to work out how to create a conditional. (Start by understanding Python :-) )

[kamilkrzyskow]

In your OP you said:

I have enabled Isso comments on my site. For pages that have comments enabled, I would like to include the heading Comments in the table of contents.

For pages that have comments enabled,

So how are the comments enabled for specific pages in your docs? The same conditional should apply here in the hook unless I'm missing something 🤔

The complexity of the problem doesn't really require for you to learn Python / MkDocs first, ChatGPT or some other AI should be able to modify the example above with additional context on how you control the comments section.

[woter1832]

Hi @kamilkrzyskow,

You're correct in that I want it to only show "Comments" in the ToC when comments are enabled on the page.

With the example you provided, you said

A simple example without conditionals to limit it to the pages with comments, but should be enough to get you 80% there ✌️

To me that means you've helped me out and now it's my turn to go and work out the remaining 20%. 😃.

I confirmed that the code you gave me worked as far as you stated it would.

Like most things, AI is only as good as what you put in.
This is what ChatGPT gave me:

from mkdocs.structure.toc import AnchorLink

def on_page_content(html, page, config, files):
    
    if not page.toc or not page.toc.items:
        return
        
    # Check if the page has the metadata comments:true
    if page.meta.get('comments') == True:
        page.toc.items[0].children.append(AnchorLink("Comments", "comments", 2))

It didn't appear to work at first, but I reloaded my Python virtual environment and now it is.

Thanks again for your help.

[kamilkrzyskow]

I added more info in the edit to give some inspiration on different conditionals, which could be more convenient to use, than the flag.

To me that means you've helped me out and now it's my turn to go and work out the remaining 20%. 😃.

I somehow missed the default conditional syntax included in the comments.html template, and assumed you have your own custom conditional, which you'd later add, so yes I passed the baton to you. And you did great 😸 👍

Like most things, AI is only as good as what you put in.

Yeah, prompting can be hit or miss depending on the lack of specificity. But a code example + some context should be enough to steer the AI in the right direction.

It didn't appear to work at first, but I reloaded my Python virtual environment and now it is.

mkdocs serve doesn't reimport the Python modules after changes, so yes, a restart is required to reload the new logic.