Spec: Fix table of content generation

[ajantha-bhat]

Table of contents in the spec web page is not generated for spec and its subsection after #10948. It is super hard to navigate the spec without the table of contents.

The reason is mkdocs only consider first H1 for TOC generation.
More info: squidfunk/mkdocs-material#818

So, keeping spec as H2 and adjusted its sub topics.
Note that the double # removal is not fully reverted, only added back one # . It is still kept at the same level as expected in the PR#10948

Also locally verified the new table of contents by building it in the site directory using make serve and hosted at http://localhost:8000/spec

[RussellSpitzer]

I think this is probably a reasonable thing to do. Looking online, apparently switching to a single H1 element will also help out screen readers and accessibility software as well so sounds like a good thing to do. I would like to hear if anyone else has strong opnions though, especially since we have a few inflight Spec changes.

[ajantha-bhat]

ping @rdblue

[rdblue]

I think that this is the only problem. It appears that if there are multiple H1 sections, only the first one shows up in TOC. For the other changes, we do want to avoid over-nesting, which was originally added a few website iterations ago to get things to stop showing up in the TOC.

I think for at least a few of these, we can just change Specification and not other sections. For example, Terms is already H3, so there's no need to make it H4 because there is no intermediate H3 level above it. Everything before Schemas and Data Types falls in that category.

[ajantha-bhat]

ok, I just changed spec to H2 and reverted other changes. Rendered site LGTM.

Updated the PR.

[rdblue]

Because the container (specification) is going to be H2, I think this is a decision point. Do we care that things beyond this point are nested within Specification? I think I would rather have headings that are more distinct in the body of the spec than worry about these sections being nested within Spec. I'm curious what other people think though. @RussellSpitzer?

[ajantha-bhat]

ok, I just changed spec to H2 and reverted other changes. Rendered site LGTM.

Updated the PR.

[danielcweeks]

@rdblue I think we want to add additional nesting because we can limit the depth in the ToC configuration. That way we can have proper structure and not have the table of contents explode.

[ajantha-bhat]

The maximum depth we have is 3, do we have any plan to add depth limit? If not, maybe we don't have to argue on this.

[RussellSpitzer]

I really don't have any preference. I'm fine with just pumping all the nesting one more step deep.

[danielcweeks]

This isn't right though. The Specification header should be above the others (e.g. Schemas and Data Types) not at the same level.

[rdblue]

Okay, that sounds fine to me.

[ajantha-bhat]

TOC with this change

[danielcweeks]

@ajantha-bhat I feel like this has bounced back and forth on the levels, but we should be focused on getting the structure correct first and then addressing the ToC. This current version has Specification at the same level as its children, which is not correct.

L2/H2 should be:

## Format Versioning
## Goals
## Overview
## Specification
## Appendix A: Format-specific Requirements
## Appendix B: 32-bit Hash Requirements
## Appendix C: JSON serialization
## Appendix D: Single-value serialization
## Appendix E: Format version changes
## Appendix F: Implementation Notes

Everything else should be nested below.

[ajantha-bhat]

@danielcweeks: Thanks for the feedback. I have updated it accordingly.

New TOC looks like this.

[rdblue]

I think this is fine. @danielcweeks is the organization what you want?

[danielcweeks]

@ajantha-bhat looks like we have conflicts. It would be good to get this in, but I don't think this section of the docs is tied to the 1.7.0 release.

[ajantha-bhat]

@danielcweeks: Thanks for the review. Conflict was due to recent row-lineage merge. I have resolved it now. PR is ready.

[RussellSpitzer]

Thanks @ajantha-bhat and @danielcweeks , @rdblue , @manuzhang and @amogh-jahagirdar for review