Add support to extract underline-ish title (setext-style headings)

[hason]

The util function get_markdown_title supports only ATX-style headers. It should also support:

A level-one heading
===================

A level-two heading
-------------------

[waylan]

I'm closing this as a duplicate of #1826. As the discussion there is long and covers multiple issues, I've copied the relevant comment below. Also note that in #1843 we have explicitly documented that setext style headers are not supported.

The page title is set in mkdocs.structure.pages.Page._set_title. The mkdocs.utils.get_markdown_title function actually extracts the title from the Markdown source and would need to be significantly refactored as it currently assumes the header is contained on one line only (it doesn't support setext-style headers because they take 2 lines). Note that the title is set on the page before the Markdown source is rendered to HTML and this is non-negotiable. It would be easier to get the header from the rendered HTML (which would eliminate any concern about which format was used), but MkDocs needs the title to be set at an earlier stage than when it renders the Markdown to HTML. This is documented behavior in the Plugin API which we have promised to continue supporting. Also, I will only consider a change which enforces the use of an H1. If the first header is an H2, then the page title should be defined elsewhere (such as in meta-data) and a custom theme template would presumably be inserting the page title as an H1 separate from the page body.

Finally, this is very much something which could be addressed by a plugin. I expect either the on_page_markdown or on_page_content events could be used to overwrite the page title based on the Markdown source or rendered HTML respectively. As a third-party plugin, you could then use whatever criteria you want to define a page title.