How to change content titles in navigation?

[bleudev]

I want to change titles of navigation contents. For example on this picture, i want to do:

• keys
• values
• items
• default
• reverse()
• etc

I don't want to change markdown titles from # sort() -> UDict[KT, VT, CDV] for example to # sort(). I want to change only navigation titles.

[squidfunk]

You can list all links in mkdocs.yml in nav where you can explicitly set the navigation title. Otherwise, there's currently no easy way to do that, except for writing a custom hook to overwrite the title with a custom front matter attribute. Unfortunately, title handling is still not quite well defined in MkDocs and there are several problems with it 😕 In fact, it is a very controversial topic that has been discussed extensively without finding a one-size-fits-all solution (yet?):

• Header and navigation sidebars display incorrectly arbitrary markup mkdocs/mkdocs#3357 (76 comments)
• Consider changing the precedence of title sources mkdocs/mkdocs#3532 (32 comments)
• smart section titles when no navigation is configured mkdocs/mkdocs#3356
• Mkdocs no longer respecting set display text for same .md files. mkdocs/mkdocs#3710

I recommend reading from top to bottom, if you're interested to learn more about it. IMHO, this needs to be addressed in MkDocs, i.e., to fully define title handling and make it more flexible. It's currently too static to cater to all use cases and hard coded. From my knowledge of the code base, it could theoretically be made configurable to cater to different use cases.

---

Technical remark to the informed reader: we could, theoretically, use page.meta.title in nav-item.html over page.title if defined, but that would mean that it would always override any title set in nav, which might not be desirable, since we do not know where the title was extracted from when rendering the template. It is also not in line with how MkDocs deduces the page title:

Checks these in order and uses the first that returns a valid title:

1. value provided on init (passed in from config)
2. value of metadata 'title'
3. content of the first H1 in Markdown content
4. convert filename to title

In this case, 2. and 1. would need to be switched, so we would deviate from MkDocs behavior, which we do in some cases (for the header and social cards already), but the navigation resembles nav, so it's a different problem. Also, changing behavior here might annoy some users, while others might find it to improve the situation. Hard to decide. CC @kamilkrzyskow

[squidfunk]

Addendum: making title precedence configurable might be something to raise as a feature request to the maintainers of MkDocs. Tom is actively working on a new version of MkDocs, as he started to take funding, so it might be a good idea to discuss this while he's in the initial design phase. Always better to know more requirements upfront ☺️ You could create a feature request on MkDocs' issue tracker.

[kamilkrzyskow]

As for the navigation part and issues related to it:

1. In the Gothic Modding Community we're using the awesome-pages-plugin for easier semi-automatic nav management and the mkdocs-static-i18n plugin for multi-lang support. You might ask why did I mention that?

   Well, using the automatic navigation setup results also in using the automatic navigation titles, which aren't the best by default, as they force title (capital first letter) on most unnamed things. Fortunately as a sort of hack, the i18n plugin provides a way to translate names based on a mapping, and we're using it to "translate" the default language as well from the default title case to the correct case 😅

   • https://github.com/Gothic-Modding-Community/gmc/blob/a8ebc286b173aae77f4c6284d159ad772536e5cc/mkdocs.yml#L153-L164

   We're using this hack mostly for directories (sections) that don't have their own manually created .pages file configuration, that would allow to set the title, but it should work for overriding other pages titles as well. This hacky usage of the i18n plugin could be used as an alternative to creating a hook to do that. However, a limitation of the i18n plugin is that it doesn't support the Blog plugin at all, but another hook can patch it to ignore blog files. 😅

2. Another case where we needed to adjust the title, was the search index. We wanted to use the title: name from the mata front-matter in our social cards, but wanted the #h1 title in the search results for better searchability. So we patched this with a hook as well.

I totally agree that, MkDocs should be the one to provide a standard for various things related to file management, navigation management, i18n management, threading management etc. that would be used by the themes and plugins in unison.
I'm not really a fan of the async based approach of the next iteration, but that's the future I guess 🙄
Also all of those changes will impact the Material theme the most as it dabbles in a lot of different aspects of design, and does a lot of it with a custom approach, as there is no standard 😅

---

As for the issue at hand, I think the OP asks about the TOC which is integrated into the navigation via a theme feature.
The toc should be generated via the toc markdown extension.

Looking at source code of the typeset Insiders' plugin I see you're modifying page.toc.items in the on_page_content event.

• https://github.com/squidfunk/mkdocs-material-insiders/blob/master/material/plugins/typeset/plugin.py
  and to do it you're processing the HTML with regex.

So I guess to change TOC titles it would require a similar amount of effort, either in a hook or a plugin form.
There is no straightforward way to change the TOC titles.

[squidfunk]

🤦‍♂️ @kamilkrzyskow I didn't realize we were talking about the TOC! In that case, you can set data-toc-label for a section headline to explicitly define the title in the navigation (remember to activate Attribute Lists extension):

# sort() -> UDict[KT, VT, CDV] { data-toc-label="sort" }

[kamilkrzyskow]

🤦 I only read the usage options and didn't find anything there, didn't see the Custom Labels right above that section.
Great find ❗

[squidfunk]

Yeah, it's hard to decide what needs to go into our documentation and what other projects we can expect users to know and study, as we cannot possibly mirror and copy all information from upstream dependencies. This is a prime example.

[bleudev]

🤦‍♂️ @kamilkrzyskow I didn't realize we were talking about the TOC! In that case, you can set data-toc-label for a section headline to explicitly define the title in the navigation (remember to activate Attribute Lists extension):

# sort() -> UDict[KT, VT, CDV] { data-toc-label="sort" }

I Tried it, but my documentation only on page where i wanted to use data-toc-label toc disappeared. I tried to remove this attribute, but on this page toc was disappeared, but on index page only there is toc. It not works in mkdocs serve and GitHub Pages.

https://github.com/honey-team/ufpy-website/tree/0.1-docs - code (only 0.1-docs branch)
https://honey-team.github.io/ufpy-website/0.1-docs/useful_classes/udict/ - page where toc doesn't work

[kamilkrzyskow]

@bleudev
Check your headings:
https://github.com/honey-team/ufpy-website/blob/511450dc32f40667a1d6a856a4f7d073bb413ac8/docs/useful_classes/udict.md?plain=1#L7-L19

In this file, I see 2 H1 level headings with a single #

• # UDict class
• # class UDict[KT, VT, CDV]

I believe there can only be a single H1 for the toc to generate properly in Material for MkDocs.
So change the second one to ## class UDict[KT, VT, CDV]