Page_Title is "None" on root document

[Eonasdan]

{{ page_title }} is displaying as "None" despite my mkdocs.yml configuration as such:

pages:
- Usage: 'index.md'
- Installing: 'Installing.md'

I just updated to version 0.15.3. This wasn't a problem with whatever version I had before. This only happens to the index page.

[waylan]

I'm not able to reproduce this. Which theme are you using?

[waylan]

Ok, I see it now. the problem does not manifest itself in the MkDocs theme without modification. Once I modified the theme (by inserting {{ page_title }} randomly in a template), the problem presented itself. I noticed that {{ page_title }} is called at mkdocs/themes/mkdocs/base.html#L13 but is wrapped in an if statement. Sure enough, on the "home" page the title is not the title of the page but the site_name. Although, in that case, I think the site_name is probably the correct thing to display -- which explains why this problem was not caught before now.

[waylan]

This change happened quite a while ago in 61173d1. I understand why that change was made, but I don't agree that page_title should be None for the "homepage". It should still be the "title" of the page if it has one. The template should be using a different mechanism to identify the "homepage" IMO. For example, only the "homepage" gets a page_description. That is None for all other pages. Although, page_description hardly seems like an intuitive way to identify the "homepage". Why not just include is_homepage in the context?

[d0ugal]

I think you can already tell if the page is the homepage with {{ current_page.is_homepage }}. We should use that instead. Also, rather than using {{ page_title }} we should probably use {{ current_page.title }}.

[d0ugal]

Reclassifying as a bug, as I'm not sure what decision is needed but we should fix this 😄

[waylan]

The Needs design decision label was added as I was asking for clear direction on how we want to name the various context items. Currently there is quite a bit of inconsistency. Some things which are page specific are named page_<item> (ex: page_title) while other things are just <item> (ex: content). Nothing uses current_page.<item> as per your suggestion (personally, I find "current" redundant as there only ever is one page per page).

As a reminder, while MkDocs creates an instance of a Page class for each page, and that class holds the data for a page, the instance is not passed to the template. Instead, the get_page_context function is passed the Page instance and returns a dict of the various items with inconsistent naming. And page.is_homepage is not passed to the context as all.

My recommendation would be to pass the Page instance directly to the template (potentially removing the need for the get_page_context function). However, this would be a backward incompatible change and require custom and third party templates to be changed. I suppose, for the next release we could pass in both and give users the opportunity to update their templates. Not sure how to issue a warning if a template accesses a deprecated context item though.

[d0ugal]

As a reminder, while MkDocs creates an instance of a Page class for each page, and that class holds the data for a page, the instance is not passed to the template.

Actually, it is passed. current_page is the page instance. This is why I suggested accessing the property that way in my previous comment via current_page.is_homepage which calls this property method. We actually use this already in both themes (read the docs, mkdocs).

I think we should move towards accessing properties rather than creating variables for everything. this will take a bit of a migration process - we could make both available in 0.16 and then remove the old in 1.0, if we can make that the next release. I think there is a hook in jinja2 to handle unknown variable names, we could probably come up with a warning/error with that.

I agree "current_" is strange, we don't need that.

We probably want to define and document a new context in detail and use that. I expect we will want a few global variables only, these spring to mind, but there might be more:

• Page (what current_page is now)
• Config (to access the mkdocs config)
• Menu (all the pages)
• Table of contents (for the current page)

(Note, I avoided giving them variable names, just starting to think of everything that we need to access).

[waylan]

You are taking about the nav stuff. Outside of nav the first part of your comment does not apply.

The second part is very helpful though.

[d0ugal]

You are taking about the nav stuff. Outside of nav the first part of your comment does not apply.

Sorry, then I must be totally confused because I don't know what this means either. This issue seems to be over my head.

[waylan]

Actually, it is passed. current_page is the page instance.

Well don't I feel dumb. Sorry, you are correct, I missed that. Then all we need to do is deprecate many of the other page-specific context variables and switch the templates to use the page instance.

The real issue then is how to deprecate the variables: page_title and page_description, which are redundant. And it would make sense if content, toc, meta, and canonical_url were all on the Page instance as well.