Add workaround for TableOfContents h1/h2 hierarchy issue

First, some background is necessary. As noted at the hugo documentation site,
https://gohugo.io/content-management/toc/, the table of contents module does
not currently let you change which heading levels should be rendered. This
creates a slight issue as follows.

Let's say you have a markdown document and you use this template. The <h1>
tag is the title for each page, as set in the frontmatter. In markdown, that's
also the single hash/octothorpe/number sign marker for a top level heading.

By convention, it's typical to have a single h1> element of the same font size
on each page. Naturally, the ideal behavior is to then make all elements <h2>
or lower. As noted by Mozilla, this is even a loosely defined convention:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements

Now, this is all well and good, until you read more into the issue above.
Essentially, Hugo generates the table of contents starting with <h1> elements
from the markdown output. If you don't have an <h1> element, Hugo will render
the level associated with <h1> anyway and then indent all subsequent levels
based on this non-existent hierarchy. You can make the table of contents look
better by adding an <h1> element to the page, but this creates the conflict as
described above. You end up with two <h1> elements, which is antithetical to the
spec, only to create a correct looking table of contents. And one again, those
two <h1> elements will make your page look bad because they have the same font
size.

This is easily shown graphically, as is documented in the pull request.

A discussion exists on gohugoio/hugo talking about the heading level issue
in the table of contents system, here:

https://github.com/gohugoio/hugo/issues/1778

This is a slightly maddening issue, because it's closed, but in it many people
have identified this issue as a problem and patched it with one way or another.

My commit introduces the patch from @HenrySkup, which is located here:

https://github.com/gohugoio/hugo/issues/1778#issuecomment-522222658

This commit specifically will parse and remove empty headings in the generated
output from the `TableOfContents` module, thus creating the proper indentation
level as expected, and not requiring breaking the html spec, nor making pages
look nasty. It's backwards compatible with existing markdown written under the
broken assumption, by way of rendering correctly with existing <h1> elements,
while simultaneously fixing any table of contents generated with only <h2> and
subsequent heading levels by indenting them the correct amount each time.

This was tested against Hugo v0.58.0.

1 files changed, 4 insertions, 2 deletions

diff --git a/layouts/_default/single.html b/layouts/_default/single.html
index 2fc350e..43fabdf 100644
--- a/layouts/_default/single.html
+++ b/layouts/_default/single.html
@@ -45,8 +45,10 @@
 {{ define "side" }}
   {{ if and (gt .WordCount 0 ) (ne .Params.toc "false") }}
     <div id="toc" class="Box Box--blue mb-3">
-      <b>{{.Title}}</b>
-      {{ .TableOfContents }}
+      <b>{{ .Title }}</b>
+      {{- $toc := .TableOfContents -}}
+      {{- $toc := replaceRE `<ul>\n<li>\n<ul>` `<ul>` $toc -}}
+      {{- safeHTML $toc -}}
     </div>
   {{ end }}