How to make auto-generated (filename-based) document titles have permalink?

[ryran]

For our page titles, we mostly rely on the filename; however, we of course sometimes want to override that (especially if it's necessary to have hyphens in the title) by making the first line be the desired title, e.g.:

# Explicit title here to override title generated from filename

Content blahblah

When we do that, the title ends up with a permalink, which is good. How can we make it so the title ALWAYS has a permalink? (Even when it was just generated from the filename.)

The reason I want to do this: I think that permalink next to the title would be the perfect thing to hijack in order to generate a cleaner URL for sharing -- e.g., since I'm using a private repo in GitLab, I want to convert something like

https://project-group-fd7c2d0a7d761b2fe7722c69fad518f193fd3bb5b95f1dc1afdc3.pages.example.com/Dir/Subdir/Doc/

to the shorter and more canonical

https://group.pages.example.com/project/Dir/Subdir/Doc/

[kamilkrzyskow]

Hello @ryran,
the permalinks for the headings in the content are generated in the toc markdown extension, if you don't have the # title in the file, the theme extracts the auto-generated title from the filename and adds a <h1> tag to the page:

mkdocs-material/src/templates/partials/content.html

Lines 31 to 40 in 5108432

	<!--
	Hack: check whether the content contains a h1 headline. If it doesn't, the
	page title (or respectively site name) is used as the main headline.
	-->
	{% if "\x3ch1" not in page.content %}
	<h1>{{ page.title | d(config.site_name, true)}}</h1>
	{% endif %}
	<!-- Page content -->
	{{ page.content }}

So there is no permalink added here, probably to avoid any id conflict with another permalink inside the content.

You can override the content.html partial with customization and add it:
https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

---

Also for consistency, as mentioned in another discussion:

Apart of that I wrote a guide about dynamic templates overrides:

• How to dynamically override templates with hooks? #5060

Unfortunately, I can't find the time to edit it for the newest implementation of my hooks and mkdocs-material.
But you can still use the guide as a "reference guide" and use the updated solution, which uses 2 hooks:

• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/theme_overrides_manager.py
• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/language_flags.py

---

You can add the hyperlink also using JavaScript, similar to adding a button mentioned in:

• How to add a "share link to this page", especially for private GitLab/GitHub pages sites? #6849

[ryran]

Thanks for the explanation Kamil. I'm not gonna try to do this. While I don't like the inconsistency, I'm gonna let that go and stick with #6849 for page link button.

[kamilkrzyskow]

Sure thing, since you have most of the logic done in #6849 then you only need to add the appropriate HTML elements next to the first heading ✌️ The process would be quite similar to what you've already done.