-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Consider changing the precedence of title sources #3532
Comments
Maybe there is a way to achieve this immediately with a hook? |
I think this is a behavior of mkdocs-material, or I don't understand what you're describing. |
Aha no, I see. Although both of the shown examples of how the page title is displayed are unique to mkdocs-material, the source of that title is deduced by MkDocs. It's presumably also put into the |
Yeah it's a good point. MkDocs just expects you to use the same title in the navigation and in the first heading. A page doesn't have multiple kinds of titles. This feature would be tough to introduce conceptually and would have to be an awkward new config entry 😞 |
Actually all themes at the moment explicitly use the same mkdocs/mkdocs/themes/mkdocs/base.html Line 16 in 7186f4c
mkdocs/mkdocs/themes/mkdocs/base.html Line 100 in 7186f4c
My only idea is to add a new attribute and then themes could use it. There actually already is such an attribute but it's private - mkdocs/mkdocs/structure/pages.py Line 281 in 7186f4c
|
cc @squidfunk for visibility |
In Material for MkDocs if I set the following then the title is in fact updated appropriately without changing the text in the sidebar: https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-title Is there some way I can artificially set this metadata attribute in a hook based on the level 1 header? |
Title handling is broken since MkDocs 1.5 (see #3357). There are some instances where markup ends up in My 2 cents. |
I just tried setting the front matter via a hook but it looks like at that point the metadata is already stripped out and processed. Is there a way to set the title based on the h1 via a hook? |
@oprypin Do you know of a way? |
I tried looking into the code base but I still am not sure unfortunately. |
@ofek It is extremely convoluted to bypass the title machinery right now in the way that you want, which is why I wasn't suggesting anything. Could you wait for further developments regarding titles |
Sure I'm fine with waiting sorry to bother! Although, outside of titles is there any way to change front matter via a hook? |
No but it always was allowed to contain markup 😞 and seems like it will stay this way. You've been saying it like MkDocs 1.5 changed this but actually it didn't change anything for |
For this change itself, I am interested to know if you'd be happy to apply it when the new attribute is available, @squidfunk . {% if page.title and not page.is_homepage %}
<title>{{ page.content_title | striptags }} - {{ config.site_name }}</title>
{% else %}
<title>{{ config.site_name }}</title>
{% endif %} {{ page.content_title }} You've added this special case to prioritize as follows:
But instead this would now prioritize as follows:
Which would make more sense to both me and @ofek |
Honestly, I'm having a really hard time committing to anything with "yes" or "no" right now, because there are so many changes related to title handling in the making that I'm not able to keep up. What you're proposing sounds good, but that is only a guess. There might be side effects that break things. If this gets merged, IMHO, the maintainers of MkDocs might consider a prerelease to give plugin and theme authors enough time to test and adjust. |
The existing prioritization is based on the idea that explicit trumps implicit. If a user explicitly defines a title for a page (in nav or meta-data), then that title is used. However, if the user does not explicitly define a title, then get the implied title from the first That said, there have been many requests over the years to have the nav title only be the label in the site navigation, but not be the page title. However, I have always rejected that as I am not aware of a graceful way to make that change for the many users who have all of their page titles defined in their nav. Personally, if I have a title defined in my nav, under no circumstances do I want a future update to MkDocs to suddenly start using the I suppose an additional config option could be added which basically causes nav titles to be ignored. But then why is the user defining them? As previously noted, the nav is not separate from the pages collection and so there is no second nav-only-title. Unless the config setting was added at the same time as some new nav object which was separate from the page objects. |
Thanks for the feedback. I still believe that there's no way that the current behavior makes more sense than the proposed behavior, but with this feedback in mind, it will surely break at least some users' expectation from pre-existing behavior. Then perhaps my change should stop at just adding the new attribute, without changing built-in themes. |
And I do think that at the very least what mkdocs-material currently does would make a lot of sense for all themes. Namely, <title>{{ page.meta.title or page.title }}</title> because with similar logic, why on earth would the user specify the meta title if it's impossible for it to be used if the site specifies titles in the nav config. |
Please see the pictures I posted in the OP. It is desirable to have the actual title be more verbose which is undesirable in the short link one would click on the side. |
Simply adding the new attribute will enable mkdocs-material to change the source of this floating pop-out title element. (Which is a totally unique concept in this theme.) I think that will be uncontroversial. The question whether it will also make sense change the source of the |
OK, I had to re-read a few times to make sure I understand. If the proposal is the following, then I'm -0:
In some pages of mine, I have the opposite case of @ofek's: Markdown title is short, nav title is longer and more descriptive, so I want the nav title to be used as HTML title (current behavior). With this proposal implemented, I can still achieve that by copying the nav title in the front-matter |
(I'm therefore also totally open to a new option for giving precedence to nav or Markdown titles) |
Alright, so there will be no change to how This can enable more flexibility in hooks (example pypa/hatch#1239) and new possibilities for themes with advanced features (example #3532 (comment)) |
Or well actually I am still interested to bump the priority of page.meta.title over the nav title , like mkdocs-material already does |
Some more background. MkDocs didn't always to support defining page titles in the meta-data. And so if a user wanted a page title to be something other than the the So nav was the oldest and only option to begin with. (with filename as a fallback) Those users need to continue to be supported. Each additional option was built later, so they all have lower priority. And as explicit takes precedence over implicit, then we get But yes, a theme (or a custom template provided by a user) could conceivably check |
@pawamoy Can you please share an example? I think in the vast majority of cases users would benefit from the default sourced from the |
And you might be right! It would be interesting to look at current usage of meta+nav titles (only working with mkdocs-material IIUC) compared to nav+markdown titles, to see which use is the most common. I'm going to bed but I'll share an example tomorrow :) |
|
We can't make a switch like that, no. It'd break other users expectations. Echoing @waylan's comment above... "if I have a title defined in my nav, under no circumstances do I want a future update to MkDocs to suddenly start using the <h1> of the page as the page title."
We should avoid configuration options where possible. I'd suggest that if there is an approach to resolving this, then it should be through theming and passing sufficient nav + toc context to the theme. There's also a design flaw that's been pointed to...
That's something that I think? goes way back to early versions of MkDocs. A much neater approach would be to just be explicit. A nav config that always includes titles would be how I'd approach this if I was looking at a redesign. The |
I just had a talk with @pawamoy on another backlog grooming call that we did today on this very topic, after we didn't have enough time yesterday. It's important to know that there are many users that just throw a folder of Markdown files at MkDocs without specifying an explicit structure, which is an awesome way to get started quickly. There are also several plugins that allow to manage explicit navigation auto-magically outside of All of that just from the top of my head – deeper evaluation required. |
Related #3356 |
Specifically, on this page https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data I would prefer that the level 1 headers take priority over the navigation name, or an option to do so.
I'm realizing that deriving the title from the navigation sidebar does not provide a good user experience and I would like to avoid having to add meta-content to every page. I will use a real example: https://hatch.pypa.io/1.9/config/static-analysis/
The sidebar already represents clearly defined sections and in this case the entire sidebar relates to config so it would be very verbose to add the word "configuration" to every name.
Here is the full(ish) picture showing the desired title as the level 1 header:
A consequence is that when you scroll down with Material for MkDocs the title on top is now no longer specific:
As well as the social card that shows up when you post a link to a page in Slack or Twitter or Discord:
The text was updated successfully, but these errors were encountered: