Generate ToC with Hugo rather than JavaScript

[zecakeh]

Thanks to the .RenderShortcodes function added in Hugo 0.117.0, we can include the CS modules and all the headings are included in the generated ToC, with unique IDs. This avoids to do it with JavaScript in the browser.

This should fix the issue in #1841.

This might however leave some duplicate IDs in the code generated from OpenAPI definitions.

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr1851--matrix-spec-previews.netlify.app

[richvdh]

hrm. We switched to {{< deliberately (#1205). Switching back seems like it will break things?

[richvdh]

Oh, this is ok because the cs-module shortcode is switching to .RenderShortcodes instead of .Content? But why is it necessary?

[zecakeh]

Hugo is lazy and uses the markdown renderer to detect headings and construct the headings tree.

.Content returns a page rendered as HTML, and {{< means "don't process the data returned by this shortcode with the renderer", so the renderer in the main page just replaces the shortcode with the module page rendered as HTML without processing anything, and Hugo is only aware of the headings in the main page.

.RenderShortcodes returns the raw markdown, with the shortcodes of the page already replaced, and {{% means "process the data returned by this shortcode with the renderer", so the renderer processes the full mardown of the main page and the module pages as a single document, and Hugo is aware of all the headings in the final page.

[richvdh]

for the record: this stops htmltest complaining about links with href="#"

[richvdh]

(Though, as far as I can tell, we've had such links in the ToC for ever, so I don't know why we suddenly need this now)

[zecakeh]

htmltest only tests the HTML source, the ToC was generated with JavaScript, so htmltest didn't check it.

[richvdh]

oh of course

[richvdh]

(Though, as far as I can tell, we've had such links in the ToC for ever, so I don't know why we suddenly need this now)

[richvdh]

Writing it here for want of somewhere better: I wondered if we could avoid cloning the whole of sidebar-tree.html by putting toc.html back in baseof.html. The answer is that we can, with some custom CSS, along the lines of:

baseof.html:

-            {{ partial "sidebar.html" . }}
+            <div class="sidebar-div td-sidebar-nav">
+              {{ partial "sidebar.html" . }}
+              {{ partial "toc.html" . }}
+            </div>

Custom CSS:

.sidebar-div {
    overflow-y: auto;
    position: sticky;
    top: 4rem;
    height: calc(100vh - 5rem);
}

.td-sidebar__inner {
    height: auto !important;
    position: static !important;
}

(In other words, we have to move the height and position from .td-sidebar__inner to a higher-level div.) But frankly, that looks more brittle than just forking sidebar-tree.html.

[richvdh]

Thanks!