Allow plugins to override Page when populating navigation

[squidfunk]

Following up on squidfunk/mkdocs-material#5909 (comment), I'm suggesting to adjust the logic that MkDocs implies to create Page objects from/in files, i.e., File objects. Currently, _data_to_navigation will always create (and thus overwrite) Page on everything that doesn't look like a Link or Section. Excerpt of the comment linked:

MkDocs will always generate either a Link or a Page for a file that is not excluded. As you've probably noticed, the blog plugin makes use of subclasses for pages of specific types, e.g. Post, View, etc., and relations among different concepts in the plugin are managed inside the instances of those subclasses. The problem is, that MkDocs will always generate a plain old Page instance, overwriting the more specific instance that has been generated by the plugin before after on_files and before on_nav. We could still solve it by splitting file generation and page instantiation, but this would make things much more complicated and non-linear, because during generation, we already assign categories to pages and vice versa, etc. We would need to split this into two stages, blowing up the code base of the plugin and also the runtime, as we're doing two passes. This is clearly not favorable from our perspective.

Moving forward: I believe that this problem can be mitigated with a very small but important change in MkDocs: if a File already defines a dedicated Page in file.page, MkDocs should just use that instead of creating a new one:

return file.page if isinstance(file.page, Page) else Page(title, file, config)

It's essentially a single line change in MkDocs that would make things much, much simpler for plugin developers. I've written several plugins now, and I repeatedly had to work around the oddities of this behavior.

Thus, I'm proposing to change the following line:

# Now: always create a page
return Page(title, file, config)

# Better: only create a page when one was not created before
return file.page if isinstance(file.page, Page) else Page(title, file, config)

Currently, the only way to work around this limitation is to overwrite Page.__class__ on the resulting instance in on_nav, e.g., like done in section-index, which, AFAIK, does not call __init__ or initializes instance variables:

page.__class__ = CustomPage
assert isinstance(page, CustomPage)

[squidfunk]

We just got a report for a problem downstream that is blocked by this issue and would be fixed by the proposed solution:

• Regression with nav item direct linking to blog post in 4.40.3 squidfunk/mkdocs-material#5949

We currently work around this issue with the following hack.

[ultrabug]

From a first look I don't see any downside in providing this simple patch to the page logic.

@oprypin would you agree?