CODEWITHSUNDEEP
markdowngithub-flavored-markdownmkdocs
Guy Klages
Guy Klages

Reputation: 63

mkdocs nav title different from page title

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!

Upvotes: 6

Views: 5701

Answers (2)

Maëlan
Maëlan

Reputation: 4202

I’d use meta-data too, but following a slightly different approach than what Waylan suggests.

Waylan suggests to use:

  • a nav entry - 'Short Title': file.md in the configuration file;
  • meta-data title: Long Title at the top of the Markdown file.

I propose to rely only on page meta-data:

  • meta-data short_title: Short Title at the top of the Markdown file;
  • meta-data title: Long Title at the top of the Markdown file.

I see two advantages to this scheme.

  1. You do not break the built-in semantics for XXX.title: it still means the full title. So instead of patching every use of it in the theme (and breaking the parts you missed), you patch only the parts where you want to use the short title (presumably, only the nav menu), to replace any occurrence of XXX.title by XXX.meta.short_title¹.
  2. I see the title (short or long) of a page as part of its contents. It is local to this page. Therefore, I prefer not to scatter contents between the local Markdown file and a central configuration file, nor to have to keep both in sync (and fail to do so at some point) manually. Meta-data embedded at the beginning of Markdown files enables purely local edition. I can let MkDocs generate the nav menu only from my Markdown files, with no data replicated in the global configuration file.

¹ Or rather XXX.meta.short_title if (XXX.meta is defined and XXX.meta.short_title is defined) else XXX.title.

Upvotes: 0

Waylan
Waylan

Reputation: 42627

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.

Upvotes: 3

Related Questions