mkdocs-material

mkdocs-material copied to clipboard

Contribution guidelines

• [X] I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• [X] ... the problem doesn't occur with the mkdocs or readthedocs themes
• [X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• [X] ... the documentation does not mention anything about my problem
• [X] ... there are no open or closed issues that are related to my problem

Description

So the other day I was working on a plugin that uses Markdown metadata, and things wouldn't work the way I expected them to work.

Turns out there's something very strange going on with Python Markdown's Metadata extension and MkDocs.

Long story short, I think I found out: Enabling or disabling the Metadata extension in mkdocs.yml doesn't do anything. You don't have to do it and I think it should be removed from Material's documentation.

The reason for this is that the metadata functionality is built-in natively in MkDocs, precisely in mkdocs/utils/meta.py.

This built-in functionality takes precedence over the Metadata extension. So when the Metadata extension parses the Markdown content, all metadata has already been stripped, and the extension does effectively nothing.

You can debug this by setting up a test project and watching the lines list in both mkdocs/utils/meta.py and markdown/extensions/meta.py:

mkdocs.yml

site_name: Test Project
markdown_extensions:
  - meta
theme:
    name: material
use_directory_urls: false
nav:
  - Welcome: index.md

index.md

description: Meta description

# Welcome

Lorem ipsum

Result ("lines" list)

===== mkdocs/utils/meta.py =====
['description: Meta description', '', '# Welcome', '', 'Lorem ipsum']
================================
===== markdown/extensions/meta.py =====
['# Welcome', '', 'Lorem ipsum', '', '']
================================

So I suggest to replace all references to enabling the Metadata extension (e.g., here: "~~When Metadata is enabled, t~~The page title can be overridden".

Also, if you can confirm this, I'll ask the MkDocs team if this intended behavior or should be changed.

Expected behaviour

Actual behaviour

Steps to reproduce

See description

Package versions

• Python: Python 3.9.13
• MkDocs: mkdocs, version 1.3.1
• Material: latest Insiders version

Configuration

See description

System information

• Operating system: macOS
• Browser: FF

Thanks for reporting. Very interesting! I'll look into it asap.

Fixed in 233252194. Indeed, the meta extension is not necessary. I've removed all occurrences from the docs, since it's essentially a no-op as noted.