Better page heading behavior

[mrfigg]

Search Terms

readme index heading

Problem

Issue 1:
All other pages, excluding modules.html (see #2728), have an h1 heading, while the readme index.html page has an h2 heading. This causes an inconsistent look.

Issue 2:
Many (probably most) typescript projects start their README.md files with a project name heading, which leads to redundant headings when combined with the readme index.html page title.

Suggested Solution

Issue 1:
Change the index.html heading from h2 to h1.

Issue 2 Option 1:
Add an omitReadmeHeading boolean option that skips rendering the page title heading.

Issue 2 Option 2:
Add an omitReadmeHeading boolean option that checks if the README.md file starts with a heading that matches the project name and removes it if found. This would have the added benefit of simplifying the On This Page section.

Issue 2 Option 3:
Same as option 2 but have the omitReadmeHeading option default to true.

Issue 2 Option 4 (preferred):
Check if the README.md file starts with a heading that matches the project name and remove it if found by default. This would have the added benefits of simplifying the On This Page section and not adding more options.

[Gerrit0]

Change the index.html heading from h2 to h1.

Seems reasonable.

Issue 2:

I'd prefer to introduce one option for this and #2727, called headings, which like the navigation option is a set of flags for projects + documents.

I definitely do not want to sniff the readme content to try to determine if a heading should be included. That sort of magic code has a tendency to become royally abused and require many iterations to get something that only mostly works for most people.

[mrfigg]

That sounds like a much better plan than mine.