TableOfContents

TableOfContents reads the h1 to h6 headings of an HTML string and renders a nested list of links to them. Pass it the rendered content of a CMS item to give long articles and documentation pages an outline.

Package Osirion.Blazor.Cms.Web, namespace Osirion.Blazor.Cms.Web.Components. Source on GitHub.

@using Osirion.Blazor.Cms.Web.Components

@* The headings come from the sample HTML below. It is rendered under the contents so the links have somewhere to go. *@
<TableOfContents Content="@sampleHtml" />

<div class="mt-3">
    @((MarkupString)sampleHtml)
</div>

@code {
    // A constant written for this demo, not content from a reader, so it is safe to render as markup.
    private const string sampleHtml = """
        <h2 id="toc-demo-install">Install</h2>
        <p>Sample text for the first section.</p>
        <h3 id="toc-demo-package">Add the package</h3>
        <p>Sample text for a subsection.</p>
        <h3 id="toc-demo-register">Register the services</h3>
        <p>Sample text for a second subsection.</p>
        <h2 id="toc-demo-use">Use it</h2>
        <p>Sample text for the last section.</p>
        """;
}

The demo builds the outline from a small sample HTML string and renders that HTML below it, so the links have headings to go to.

Usage

@using Osirion.Blazor.Cms.Web.Components

<TableOfContents Content="@Item?.Content" />

A sidebar outline limited to the second and third heading levels:

@using Osirion.Blazor.Cms.Domain.Entities
@using Osirion.Blazor.Cms.Web.Components

<aside>
    <h2>On this page</h2>
    <TableOfContents Content="@Item?.Content"
                     MinLevel="2"
                     MaxLevel="3"
                     EmptyText="This page has no sections." />
</aside>

@code {
    [Parameter]
    public ContentItem? Item { get; set; }
}

The built-in ArticlePage and DocumentPage render it the same way, under their own TableOfContentsTitle heading.

Parameters

Class goes on the nav. Style and Theme are accepted but not written, and other attributes on the tag are captured but not rendered.

Behavior

• Each link points to {current path}#{heading id}. The CMS Markdown renderer gives every heading an id and the HTML sanitizer keeps it, so the links work for CMS content. For a heading without an id, the component makes one from the text (lower case, letters and digits, spaces turned into hyphens), and the link only works if your page has an element with that id.
• The heading's id is read wherever it sits among the attributes of the tag, quoted or bare. A heading whose text runs over several lines is found.
• The search for headings stops after one second. On HTML that makes it take longer, such as thousands of unclosed heading tags, the outline is empty and a warning is logged.
• Headings are nested by level: an h3 goes under the h2 before it. The list shows two levels, the top-level headings and the headings directly under them. Deeper headings are not shown.
• Tags inside a heading are stripped and the remaining text is written as text, so it is HTML-encoded. Character references are not decoded first, so a heading such as Q&A, which the Markdown renderer writes as Q&A, shows as Q&A in the outline.
• The component always renders a nav with the accessible name "Table of Contents" (fixed English text), and the EmptyText paragraph when there is nothing to list. Headings are read on every parameter change, so the outline is part of the static SSR response.
• With TrackActiveHeading on and at least one heading listed, a small script (loaded through BlazorJSComponents, which AddOsirion registers) marks the link of the section being read as the page scrolls: the last heading whose top has passed a line a quarter of the viewport below the top (plus the --osirion-anchor-offset of a sticky header). At the end of the page the last heading wins. Without script the links work as they are.

Styling

Links use --osirion-text-secondary and --osirion-action-primary, with --osirion-focus-ring-color for keyboard focus. The marked link reads --osirion-toc-active-color, --osirion-toc-active-accent and --osirion-toc-active-background. The stylesheet also has print rules.

Related

• OsirionStickySidebar, to keep the outline in view while reading
• Content View
• CMS navigation components