Add floating table of contents

[rnevius]

Description

As above. In order to accomplish this, I have completely removed the defunct/mostly unused hugo-material-docs theme, and upgraded Hugo to v0.70.0 for Goldmark and .TableOfContents support.

Updates #2443 (comment)

Motivation and Context

#2443 (comment)

Review Instructions

I'm not in love with the style...but it could just be me. Part of the issue is that Sensu Docs headings are quite long (compared to something like the Grafana docs). Maybe things will look cleaner with shorter headings.

It's also possible that the startLevel/endLevel in the tableOfContents configuration need to be modified.

[hillaryfraley]

@rnevius I like the look although I see what you mean about longer headings on the page. I think we can reduce or eliminate the number of pages with unwieldy H2 lengths if I rewrite the headings in the API docs. I also noticed a couple pages with zero on-page headings, which makes the empty right-side menu look strange :D I am sure those pages need a heading or two.

One potential issue: it looks like there is something weird happening on pages that contain a highlighted shell code block. Maybe the content in those blocks isn't wrapping?

I'm seeing it on these pages:

• https://docs.sensu.io/sensu-go/latest/getting-started/prometheus-metrics/
• https://docs.sensu.io/sensu-go/latest/guides/enrich-events-with-hooks/
• https://docs.sensu.io/sensu-go/latest/reference/datastore/

It may be happening on other pages too -- I just tried to confirm it's not isolated to a single page.

[hillaryfraley]

Here's a gif that shows the issue I mentioned:

[rnevius]

@hillaryfraley nice catch. This bug has been fixed.

[hillaryfraley]

@rnevius We are wondering if it's possible to make a few adjustments:

1. Can the floating TOC have an indicator of the user's place on the page? For example, as they scroll down, can the current section displayed on the page be highlighted in some way in the floating TOC? This is the most important adjustment we'd like to make.

2. [HOLD] see Expand H2 to display H3 in floating TOC #2474 When a user clicks on one of the H2 headings in the floating TOC, can that H2 heading expand in the floating TOC to list the H3 headings it contains?

3. Can we evenly adjust the line spacing all H2 and H3 headings? I tested endLevel = 3 in [markup.tableOfContents], and the first H3 heading was closer to the bottom of the H2 heading than it was to the next H3 heading.

[rnevius]

@hillaryfraley I have updated items (1) and (3) from your previous comment. Item (2) is a little more tricky (not impossible). Can you take a look at the new state of things and let me know if this is something you'd still like to pursue?

[rnevius]

@hillaryfraley this functionality has been added. As a test, I have added the toc: false page param to /sensu-go/5.20/release-notes

[hillaryfraley]

@rnevius This is great! Thank you for all of your work.

I won't merge until Monday because I have a little bit of work to do with removing the manual TOCs from the tops of pages. But I think this one is 👍 💯

[hillaryfraley]

@rnevius I'm sorry to backtrack on this. I just discovered that the offline: false frontmatter attribute doesn't seem to be working now. When I run yarn run server --layoutDir=offline and open a local copy in my browser, I see the Supported Versions page (which should be excluded using offline: false).

edit: I pushed a commit to this branch without thinking. It's changes we'll want anyway (propagating the toc frontmatter attribute to all release notes) but it seems to be interfering with updating this branch against the base.

[rnevius]

@hillaryfraley ready for another review. The last couple of issues have been a result of different behavior with the new version of Hugo in this PR. Nice QA.

[hillaryfraley]

@rnevius thank you for resolving everything I found! This looks great. I'm going to merge it today 🎉