Tags Index: Option to render URL text from Markdown Headers instead of page.title

[annabaker]

Currently, the tags plugin allows for a Tags Index to be rendered via the tags_file definition.

In the Index, the URL text is generated from the page.title, either explicitly defined with front matter:

welcome-intro.md

--- 
tags:
   - Introduction
   
title: "This is my page title"
---

Some text

or, it is generally rendered from the title listed in the nav. For example, consider the following snippet:

mkdocs.yml

nav:
  - "Welcome":
      - "Overview": welcome-intro.md

In the above example, assuming page.title is not explicitly set, the URL text in the index would render as Overview.

This can be a problem for users in a few different cases. Mainly, say we have the following two markdown files:

welcome-intro.md

--- 
tags:
   - Introduction
---

# Welcome: an Introduction

debugging-intro.md

--- 
tags:
   - Introduction
---

# Debugging: an Introduction

And the following nav defined:

mkdocs.yml

nav:
  - "Welcome":
      - "Overview": welcome-intro.md
  - "Debugging":
      - "Overview": debugging-intro.md

In this case, the Tags Index would render something like:

[Introduction]
- Overview
- Overview

This is not very intuitive to users from this viewpoint, if two pages have the same page title. The workaround would be to set the page.title explicitly in order to render a more intuitive link, however this could be cumbersome, especially if you have a large set of tagged files like this.

It would be nice to give authors the option to render the URL text from the Markdown header itself, something like:

  tags:
    tags_file: tags.md
       use_markdown_header: true

This way, the Tags Index in the above example would render:

[Introduction]
- Welcome: an Introduction
- Debugging: an Introduction

[squidfunk]

It is the exact page title that MkDocs determines for the page, since for rendering the tags, we use page.title:

mkdocs-material/src/plugins/tags/plugin.py

Lines 148 to 150 in 9e0c005

	# Render link to page
	title = page.meta.get("title", page.title)
	content.append(f"- [{title}]({url})")

We're planning to do a refactoring of the tags plugin in the near future, so if you want, you can raise a change request and lay out your use case(s). The more input we have, the better we can gravitate towards a better solution 😊 We actually already have a (yet unshared) prototype that is much more powerful, so any input is welcome.