Provide <title> tags for doc pages

[pablobm]

The lack of <title> tags may be harming SEO (I'm thinking of people looking for Administrate's documentation).

There's also the matter that each page has two h1s, but that's another matter and can be treated separately.

Admittedly, my solution is a bit dirty. Is it worth my spending a bit more time to make it more presentable? Do you have any ideas?

[nickcharlton]

Oh that's a bit exciting.

The only alternative I can think of is to add something like YAML front matter, so each Markdown file would have something like:

---
title: The Page Title
---

What do you think?

[pablobm]

Yes, I think that's worth looking into. I have given it a go at master...pablobm:frontmatter, which builds on top of this PR. However I have noticed one snag.

Currently, we include the contributing guide from the documentation, as a symlink to the standard one that you can normally read on GitHub. The snag is that this page now has to choose to either show the main title as a markdown # title or as a frontmatter title. The former reads better on GitHub, and the latter reads better in the documentation site. See an example of what I'm talking about: https://github.com/pablobm/administrate/blob/frontmatter/CONTRIBUTING.md

What do you think?

[nickcharlton]

I think whilst having a box above the top is a bit strange, it doesn't really matter in the hope of making everything look good on the docs site (somewhere we control, rather than GitHub)

[pablobm]

Sounds good 👍 I incorporated the Frontmatter changes on this PR now.

[nickcharlton]

I deployed a review app so we can take a look at it: https://administrate-demo-prer-pr-1537.herokuapp.com/

[nickcharlton]

Two quick thoughts:

1. We should set something as the default, maybe Administrate? I'm not sure if this should become Page Title — Administrate, what do you think?
2. The index page is missing a title

[pablobm]

I agree on both. Also a third one: the pages have now lost their h1 heading. There's one in the sidebars, but I think it should be demoted (in a different PR).

Working on it.

[pablobm]

OK, first weird thing: the index page is the readme, so now we have the Frontmatter table on the project's home page on GitHub. I think this is more awkward than the previous situation with the contributing page. What do you think?

[pablobm]

Addressed all three issues.

(By the way, if at some point you think my initial proposal was better, that's fine. I'm not very attached to this code. It's a useful experiment.)

[nickcharlton]

Huh nice.

Omg, how is this such a difficult problem! We're in a much better state than we were, but let me think about it a bit next

[pablobm]

Yeah, who would have thought! 😄 No worries.

[nickcharlton]

I think this is the best approach, so I'm going to merge it. Thanks!