Always use h1 for first heading on a page

[colleenmcginnis]

Related to #2768 (specifically #2768 (comment))
Fixes #1614

I think this should force the first heading on every page to be an h1. However, this fix seems to easy so I'm not sure if I'm misunderstanding the total impact of this change. Opening this PR to see if the PR preview builds and what it looks like before fixing tests. Switched to a different approach detailed in #3009 (comment) below.

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[colleenmcginnis]

It looks like this "fix" sometimes results in pages with multiple h1 headings on (I think) pages that don't use [discrete] or [float] on all headings that should be on the same page so I'm not sure it's much of a fix after all... I'm not sure if I should dig in further or rely on just styling the headings appropriately like we're doing in #2768.

[bmorelli25]

Can you provide a double H1 example? I'm having trouble finding one.

[colleenmcginnis]

Here are all of them in the 8.13 version of the Observability guide:

• html/en/observability/8.13/apm-redis-output.html
• html/en/observability/8.13/apm-privileges-rum-source-map.html
• html/en/observability/8.13/apm-privileges-agent-central-config.html
• html/en/observability/8.13/apm-logstash-output.html
• html/en/observability/8.13/apm-kafka-output.html
• html/en/observability/8.13/apm-elasticsearch-output.html
• html/en/observability/8.13/apm-console-output.html
• html/en/observability/8.13/apm-configure-tail-based-sampling.html
• html/en/observability/8.13/apm-configure-head-based-sampling.html
• html/en/observability/8.13/apm-configure-cloud-id.html

So there are not too many in Observability docs, but in bigger/older books there are many more. For example, in v8.13 of the Elasticsearch guide 843 out of 1815 HTML files contain more than one h1.

[bmorelli25]

Discussed in metrics mtg this morning. @KOTungseth will ask Katy on Friday if no H1 is better or worse than multiple H1s.

[colleenmcginnis]

Ok I tried a different approach here: trying to use the built-in AsciiDoc document header. It looks like we set the noheader option to true. I'm not sure why or if there will be unintended consequences by turning this off, but I haven't come across a dealbreaker... yet.

It's not as simple as changing that option. This PR would also:

• Move the breadcrumbs. If we use the document header with its h1, the current placement of the breadcrumbs would be below the title. To address this, we can create a placeholder div for the breadcrumbs when we create the header, and then replace the placeholder when we go through the chunk logic. (Note: This is breaking the tests. We need to change where to expect the breadcrumbs.)
• Hide the first heading in div#content. When we use the document header, the title is still also added in the body of the doc (specifically in div#content), but we can hide that heading with CSS.
• Still hack incremental heading styles. The logic in this PR would ensure two things: (1) the first heading on each page is an h1 and (2) that will be the only h1 on the page. However, it doesn't guarantee that the headings in the main body of the doc will be incremental, but we can style them appropriately at run time.

[bmorelli25]

Clicked around a bit.

• The docs landing page is a bit broken with this new update.
• It looks like OTP highlighting doesn't work, BUT, I love that the OTP exists on every page now and is even expanded on a lot of pages due to every page starting with H1.

[colleenmcginnis]

Clicked around a bit.

• The docs landing page is a bit broken with this new update.
• It looks like OTP highlighting doesn't work, BUT, I love that the OTP exists on every page now and is even expanded on a lot of pages due to every page starting with H1.

If these are the only problems, that would be good news! For the first, this week we plan to replace the current landing page with a Docsmobile-powered one. And for the second, that is a problem that JavaScript can solve, which is my specialty!

[bmorelli25]

Awesome!

[bmorelli25]

This looks great. Nice fix for that 🐛 in 34a16c6. I've clicked around as much as I can, and I'm not seeing any new 🐛s.

🐦