Additional Heading Questions

[Foxtrek64]

Hello,

I have two additional heading questions. Firstly, what is the best way to modify the Content pipeline to nest the headings?
Currently I have this code:

var topLevelHeadings = Document.GetDocumentList(HtmlKeys.Headings).Where(x => x.GetInt(HtmlKeys.Level) == 1);

It works but it's not ideal. Looking at the content pipeline, we have this section:

new ExecuteIf(Config.FromDocument(doc => doc.MediaTypeEquals(MediaTypes.Html)))
{
    // Excerpts and headings only work for HTML content
    new GenerateExcerpt(),
    new GatherHeadings(Config.FromDocument(WebKeys.GatherHeadingsLevel, 1))
}

https://github.com/statiqdev/Statiq.Web/blob/56064f078eb08eb84aa504c1a6b4a36e2040d83c/src/Statiq.Web/Pipelines/Content.cs#L31-L36
This is where we set up the code that lets us gather headings. There is a method on GatherHeadings that lets you use nested headings:

public GatherHeadings WithNesting(bool nesting = true);

I was looking at simply removing and replacing the Content pipeline with my own, however I wanted to explore the ModifyPipeline() method a bit more first to see if I could just replace the ExecuteIf item.

---

Second question is fairly straightforward hopefully. The above code to get the top level headings works great on Markdown documents, but on Blazor pages, this returns an empty collection. The end result is that my table of contents only renders on pages which were written in markdown. Is there something I'm doing wrong here Or is this behavior normal and expected?

[daveaglick]

Fantastic question. The ideal long-term solution would be to surface the nesting option as a setting and build it in. I'll look at doing that in the next release.

In the meantime, you could certainly modify the pipeline. That has the advantage of (hopefully) being more compatible as the pipelines continue to evolve (I.e. if you release it wholesale you won't benefit from any future improvements or functionality). On the other hand, this one is tricky since the GatherHeadings module is nested a few modules deep. To modify it would end up looking like:

.ModifyPipeline(
    nameof(Pipelines.Content),
    x => x.ProcessModules
        .GetFirst<CacheDocuments>()
        .Children
        .ReplaceLast<ExecuteIf>(
            new ExecuteIf(Config.FromDocument(doc => doc.MediaTypeEquals(MediaTypes.Html)))
            {
                // Excerpts and headings only work for HTML content
                new GenerateExcerpt(),
                new GatherHeadings(Config.FromDocument(WebKeys.GatherHeadingsLevel, 1)).WithNesting()
            }))

Unfortunately you'd still have to replace the entire ExecuteIf module since it contains different "conditions" (if/elseif/else) that aren't exposed in a way you can replace just the children of that condition (though I may look at exposing those in the next release too now that I can see it would be helpful). At least that would be better than replacing the entire pipeline though.

The above code to get the top level headings works great on Markdown documents, but on Blazor pages, this returns an empty collection. The end result is that my table of contents only renders on pages which were written in markdown. Is there something I'm doing wrong here Or is this behavior normal and expected?

Yeah, it's expected unfortunately. That's what the Config.FromDocument(doc => doc.MediaTypeEquals(MediaTypes.Html)) condition in the ExecuteIf is doing. The problem is that not all Razor files are valid HTML, so we can't parse them as such an extract their headings. And even when they're syntactically valid HTML, the headings might be wrong since the Razor hasn't been rendered yet (that problem was actually confusing a lot of folks before I added the HTML-only condition). So now only files that have already been rendered to actual HTML are processed for DOM information like excerpts and headings. I don't love it, but can't think of anything better.

[daveaglick]

Added statiqdev/Statiq.Web#950 for a new setting to nest the headings

[Foxtrek64]

I did some digging into the Razor issue and I see what you mean. I was hoping it could be perhaps shifted to an earlier stage but it seems that option is not available.

I suppose a hacky solution might be to look for data-header-level attributes. I'll look at writing a custom implementation for this since I'm modifying the content module anyways. It's a bit manual which is not ideal, but it may be a good work-around for the time being.

If I find a solution that works, I'll submit a PR so the specific implementation may be discussed in more detail.