mkdocs nav title different from page title

Question

My mkdocs.yml file has nav titles that are shortened to fit onto only 1 line each in the left-side navigation, and I want the .md Markdown page title to be the un-abbreviated full-length title.

For example, while my mkdocs.yml file contains:

nav:
- BD, ML, DS: Big_Data,_Machine_Learning,_Data_Science.md
- AI, VI: Artificial_Intelligence,_Video_Intelligence.md

I want the .md page title to be:

Big Data, Machine Learning, and Data Science

...instead of copying/using the mkdocs.yml nav title:

BD, ML, DS

When I added the Markdown Page Title to the 1st line (# Big Data...) of my .md file, I get both the page title I want and the inherited mkdocs.yml nav title:

BD, ML, DS
7 min (1,939 words)
Big Data, Machine Learning, and Data Science

It seems the answer is in the mkdocs.yml file to specify a different/second "page display" name, but many Google searches have turned up nothing.

What other methods have you tried or heard of? Thanks!

Answer 1

This is only possible with a custom theme which specifically adds support for such a feature. However I am not aware of any themes which offer such a feature.

A page can only have one title. However, the page title can be defined in any one of four ways as documented:

MkDocs will attempt to determine the title of a document in the following ways, in order:

1. A title defined in the nav configuration setting for a document.
2. A title defined in the title meta-data key of a document.
3. A level 1 Markdown header on the first line of the document body.
4. The filename of a document.

Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list.

That last sentence is the key to making this work. As MkDocs is finding a title defined in the nav configuration of your mkdocs.yml config file, it never checks for a title defined anywhere else (including in meta data). It simply uses the nav title for the page as the page title everywhere (in the page.title attribute).

However, the meta-data for the page is still saved under the page.meta attribute. Therefore, you can use page.title in the nav section of your custom theme and page.meta.title anywhere else in your theme.

To define meta-data for a page, add a YAML section to the beginning of the Markdown file:

---
title: Big Data, Machine Learning, and Data Science
---

The first line of your Markdown.

Of course, define a title in your config file as before:

nav:
- 'BD, ML, DS': 'Big_Data,_Machine_Learning,_Data_Science.md'

Then in your theme you can use page.title where you want BD, ML, DS to appear and page.meta.title where you want Big Data, Machine Learning, and Data Science to appear.

If you don't want to have to create an entire new theme from scratch, you might be able to combine a custom_dir and template blocks to override only specific sections of your theme of choice.