Blank title if anything before first header

[tlnagy]

See https://dcjones.github.io/Gadfly.jl/latest/man/geometries.html for example. All the pages that appear like that in the index are like this:

```@meta
Author = "Daniel C. Jones"
```

# Geom.bar

Draw bar plots.
...

where there is a @meta block prior to the only top-level header. A probably related bug is that the header is shown again in the index if it is a named page:

[mortenpi]

This was (intentionally) introduced by #239. Idea was that we'll use the <h1> to determine nav. header only if the <h1> is the very first block. This was to be consistent with the sidebar outline.

A workaround would be to have the @meta block after the header.

By "names pages" you mean when you define the name in the pages option in make.jl, right? FWIW, the header should be shown in the pages with "-" as well.

However, I do think that we should consider this as a bug. Minimally we should ignore the @meta blocks when figuring out the outline, to be consistent with the YAML headers.

[tlnagy]

Yeah, named pages are ones that I give an explicit name to in make.jl. The duplicate entry in the index wasn't displayed when I didn't have the meta block at the beginning. That is, "Geometries" only had "Available Geometries" as a leaf. I'm using the @meta block as mentioned here #235 at the very top of files as a temporary solution until that is added to Documenter.

[MichaelHatherly]

Minimally we should ignore the @meta blocks when figuring out the outline

I'd prefer not to special case a single node type. Probably best to just look for the first <h1> header on a page and use that no matter whether it's the first, last, or any node in between.

[tlnagy]

I'd prefer not to special case a single node type. Probably best to just look for the first <h1> header on a page and use that no matter whether it's the first, last, or any node in between.

I think this is reasonable. I doubt that someone would use a <h1> and expect something else to happen.

[mortenpi]

#269 looks good, but a few things for potential future PRs:

The collect_subsections function in HTMLWriter should be updated as well -- currently the navigation menu for the HTML is inconsistent with this change (non-first page title h1s should show up in the navigation menu).

Also, what about the case when the user has a h2 (or generally any hN) before the first h1? I suppose that would be a weird case, and most likely an error on the user's part, so should we be more strict about the outline, instead of trying to accommodate this? But there should probably be a warning that "your outline is weird, some stuff might not work".

[MichaelHatherly]

Ah, yeah, good catch @mortenpi. @tlnagy would you like to also update that one?

Also, what about the case when the user has a h2 (or generally any hN) before the first h1? I suppose that would be a weird case, and most likely an error on the user's part, so should we be more strict about the outline, instead of trying to accommodate this? But there should probably be a warning that "your outline is weird, some stuff might not work".

I'd just say we should ignore any non-h1s. We could add a note in the guide mentioning it, but seems like it will probably not be too common to need an explicit warning.

[MichaelHatherly]

@tlnagy would you like to also update that one?

FYI, I'm busy sorting out collect_subsections now since I had a little bit of spare time.

[tlnagy]

Thanks @MichaelHatherly!