Use first heading as entry in navigation sidebar

[buhtz]

I am using MkDocs with the Material theme. In mkdocs.yml, I use nav: and the filenames of the Markdown files to generate the navigation sidebar.

The entries in the sidebar are built from the filenames of the Markdown files and do not match the first Markdown heading used in these files. I would like to have the first heading in each md file used as entry in the navigation bar.

And please not just another plugin. It is a simple task. I really hope that this is material-inbuild. Material itself is a plugin. I don't want to use a plugin for a plugin. I just want to use MkDocs. ❤️

[alexvoss]

Is your first heading a level one heading?

The construction of the navigation is done by MkDocs. Material is a theme for MkDocs, though it does come with a very nice set of plugins. There are limits to what it can do while staying within the boundaries MkDocs defines and the handling of titles and navigation and page titles is one of them.

[buhtz]

So you say this is a bug and is expected to work?

You can find the real (simple) setup here: https://github.com/bit-team/backintime/tree/dev/doc/manual

Or the zip (from another branch) using the info plugin.
Uploading 9.5.50-navbar-entry-from-first-level-heading.zip…

[kamilkrzyskow]

@buhtz The zip upload didn't get through, but I used the directory downloader to get the path above.

The nav title resolution is documented here:

• https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data

So the H1 heading should have higher priority than the filename. However, it's not the case in your docs, because every MD file has a HTML comment at the top of the page, and the H1 heading must be on the first non-empty line after the front-matter.

If you require to add some sort of copyright heading you'd need to do that in the front-matter meta header, so to give an example:
❌ Wrong approach

<!--
Copyright comment clause
on multiple lines
-->
# Introduction

✅ Correct approach

---
copyright: >
  Copyright comment clause
  on multiple lines
---
# Introduction

Other than that it could be seen as a bug, so you can ask for changes upstream, like squidfunk mentioned in the other comment.

---

And please not just another plugin. It is a simple task. I really hope that this is material-inbuild. Material itself is a plugin. I don't want to use a plugin for a plugin. I just want to use MkDocs

Material as a theme, also extends MkDocs, if you want vanilla solutions with no extra dependencies then you're already breaking the rules with using Material over MkDocs 🤔 This comes up again and again, MkDocs is limited in built-in features, the Material theme adds some features, but still it's not to be expected to be the final solution, so it's sort of an expectation from the end user to either look for extra plugins in the catalog or maintain their own hooks or even own theme, like Nype did with mkdocs-nype, which extends the Material theme itself, of course the increase in the scope depends on each users needs.

[buhtz]

Thank you for checking out and tearing down the problem.

So the H1 heading should have higher priority than the filename. However, it's not the case in your docs, because every MD file has a HTML comment at the top of the page, and the H1 heading must be on the first non-empty line after the front-matter.

Can you imagine a good reason for this rule?

If you require to add some sort of copyright heading

It is not "some sort" but SPDX/REUSE standard how to add machine readable copyright and license info to each file in the repo. 😄

you'd need to do that in the front-matter meta header

✅ Correct approach

---
copyright: >
  Copyright comment clause
  on multiple lines
---
# Introduction

That does not work. Two horizontal lines are rendered with text in-between. The meta data is not intended to get rendered.

[kamilkrzyskow]

Can you imagine a good reason for this rule?

• There is no comment or markdown handling, it just looks for a # character:
  • Hard-coded text reading of the file, MkDocs has its own logic to strip the front-matter header, and then a primitive scanning for the first H1 heading to avoid scanning the full file, someone decided to get the first non-empty line, probably for better performance.
• https://github.com/mkdocs/mkdocs/blob/7e4892ab2dd4a52efd95a9de407eee63310e0780/mkdocs/utils/__init__.py#L313-L315

Or this was the legacy implementation, which I remembered, at some point it got changed into a Treeprocessor, which goes over the detected tags, so I guess this could be modified to skip comment tags instead of breaking after the first tag:

• https://github.com/mkdocs/mkdocs/blob/7e4892ab2dd4a52efd95a9de407eee63310e0780/mkdocs/structure/pages.py#L557-L560

SPDX/REUSE standard

Thanks, I didn't know about it, as I'm not well versed in licencing and automated tooling. For me a LICENCE file with an explanation "every file except for ..." is good enough for the human, but now I see that adding a copyright information to each file does make it easier for external tooling to detect which file has a given license.

I checked the site and it says "edit the header to contain the following":

• https://reuse.software/faq/#step-2
• https://reuse.software/faq/#standard-copyright

So to me it looks like the HTML comment part is optional, so only the SPDX-FileCopyrightText: and SPDX-License-Identifier: are important. Unless your tooling expects these values to be in a HTML comment when used in a .md file, and MkDocs uses the front-matter section as the meta header so there is this conflict. So perhaps the rules for uncommentable files would need to be applied. There is also the case when you'd want to use the front-matter and a HTML comment together, then I think the comment would also need to be below the front-matter 🤔

That does not work. Two horizontal lines are rendered with text in-between.

Works for me when it comes to MkDocs rendering. Given the FAQ of REUSE, I would also just try

---
SPDX-FileCopyrightText: 2019 Jane Doe <[email protected]>
SPDX-License-Identifier: MIT
---
# Introduction

The meta data is not intended to get rendered.

Since GitHub and the like don't see the front-matter header as hidden meta values for MkDocs, then yes, it would render them. However, MkDocs uses the Python Markdown implementation not the CommonMark used in GitHub, so the .md files used in MkDocs shouldn't really be viewed through the lens of how they are rendered in other places like GitHub in the first place, and the front-matter header is an addition to the spec.

[squidfunk]

Thanks for isolating this as an MkDocs parsing issue. IMHO, this discussion must be moved to MkDocs, since it is essentially an MkDocs issue and not specific to Material for MkDocs. Our discussion board really suffers from being the sole entry point for each and every question in the ecosystem, including MkDocs, Python Markdown, Python Markdown Extensions, general CSS and JS questions, general web development questions, etc. With our small team, we can't offer support for everything here, so at least moving any questions that can be clearly attributed to an upstream projects upstream would be a start. Also, other projects and themes would benefit as well. I'm locking this discussion for this reason. I hope for your understanding.

[squidfunk]

And please not just another plugin. It is a simple task. I really hope that this is material-inbuild. Material itself is a plugin. I don't want to use a plugin for a plugin. I just want to use MkDocs. ❤️

I think there is a misconception here. Material for MkDocs is not a plugin, but a theme that bundles further plugins. The navigation itself is built by MkDocs, the underlying framework. Thus, this must be taken upstream, as navigation title extraction is not something that is theme-dependent – themes only render what they get, as do we. Closing as upstream matter.

[buhtz]

mkdocs/mkdocs#3908