Ignore specific headers

[XhmikosR]

Hi, @allejo.

Thanks for doing this, I was about to do it myself, so it saved me a lot of time. :)

Now, I'm in the process of switching to your solution in Bootstrap.

The only change I made so far is switch the comment directive to {%- comment -%}...{%- endcomment -%} so that we don't get any useless whitespace in the output. And a trivial end-of-file linebreak.

The thing that we seem to be missing is the ability to ignore a specific selector or selectors. For example, we need to ignore any header inside .bd-example from being added in the TOC.

I'll see if I can find a solution myself, but I'm opening this to track the issue.

[allejo]

Glad this could save you some time 😄

Is this the type of structure you're looking at?

<h2>Heading 1</h2>

<div class="bd-example">
    <h2>Sample Heading</h2>
</div>

You would need the toc to only include "Heading 1" but ignore "Sample Heading"? Or does "Sample Heading" have a class="bd-example"?

If it's the former, I'm open to clever ideas on how to achieve this. At the moment, the toc is just blindly pulling out headings and doesn't really know about the structure of the HTML.

If the headings have a class to ignore, that should be pretty straightforward to add.

[XhmikosR]

Our structure is similar to that, yeah.

<h2>foo</h2>

<h2>bar</h2>

<div class="bd-example">
    <p>foo</p>
    <h4>Sample Heading</h4>  <!-- we don't need this -->
</div>

<h2>bar</h2>

<h3>bar</h3>

So it's the former case you mention above. I guess we could try extending it later if needed :)

I had a quick look but couldn't make the loop it work properly at the limited time I spent.

Basically I used node contains include.ignore but then the loop exited without continuing to the remaining of the headers.

[allejo]

So I've pushed f94a076, which should fix removing any extra whitespace from the generated TOC. Adding {%- comment -%} wouldn't clear any extra whitespace since that comment is inside a {% capture %} and the {% capture %} value is cleared before the TOC is outputted. The include purposely doesn't end with a new line so no extra whitespaces are added, but since it's HTML it shouldn't really matter anyways :)

The whitespace control (e.g. {%-) is a new thing in Liquid 4 (Jekyll 3.5+) but any version earlier than that would throw an error. Even though GH Pages is using Jekyll 3.6 now, if I can keep this snippet working further back with no effort, then I'll take it 👍

---

The problem I'm seeing right now by trying to exclude headings inside of a selector is, I can loop through the nodes and find bd-example then I could exclude all of the headings until I find the next </div>. However, I can't reliably tell when to start tracking headings again. See this example:

<h2>foo</h2>

<h2>bar</h2>

<div class="bd-example">
    <p>foo</p>
    <h4>Sample Heading</h4>  <!-- we don't need this -->
    
    <div class="row">
        <div class="col-md-6">
            <h5>Nested Heading</h5>
        </div>
        <div class="col-md-6">
            <h4>Heading would be tracked again</h4>
        </div>
    </div>
</div>

<h2>bar</h2>

<h3>bar</h3>

Sure, I could make it a unique tag like <section class="bd-example"> and be able to end at the next </section> I see but I just have to hope there aren't any other nested <section> elements.

At least, this is the approach I was thinking of but it wouldn't reliably work. Clever approaches are welcome!

[allejo]

We could introduce a custom directive, like <!-- toc-ignore -->...

Something like this:

<h2>foo</h2>

<h2>bar</h2>

<!-- toc-ignore -->
<div class="bd-example">
    <p>foo</p>
    <h4>Sample Heading</h4>  <!-- we don't need this -->
    
    <div class="row">
        <div class="col-md-6">
            <h5>Nested Heading</h5>
        </div>
        <div class="col-md-6">
            <h4>Heading would be tracked again</h4>
        </div>
    </div>
</div>
<!-- /toc-ignore -->

<h2>bar</h2>

<h3>bar</h3>

[XhmikosR]

That is a sensible solution, indeed. But ideally we shouldn't have such comments in the final HTML.

I know it's hard because I also tried finding a solution myself :/

If you don't find any solution, no worries, I'll still use this in other projects :)

[allejo]

I'll continue to see if I can think of a more reliable solution, but I'd think a plug-in that's actually aware of the DOM would be better suited as a solution to this problem.

[XhmikosR]

Thanks for your time.

If you find a clean solution please let me know, otherwise feel free to close this.

[allejo]

@XhmikosR would a solution like this work for you? Take a look at the feature/header-exclusion branch and the respective test. It currently relies on bd-example being a <div> but that could probably become a bit more robust.

Any other possible HTML structures you guys have that I could test against?

[XhmikosR]

@allejo: huge thanks for trying to sort this!

I tried that branch in https://github.com/twbs/bootstrap/tree/v4-dev-xmr-jekyll-toc-alt and while it doesn't include the bd-example headers, it also skips some valid ones. For example for our alerts page I end up with just 3 links in TOC:

Examples
  Link color
  Dismissing

[allejo]

Yea... Being able to handle and work with the XML is definitely needed or at least would be helpful to support any given structure.

What I currently have to work with, is this sample which matches a similar structure to the alerts page.

<h2 id="foo">foo</h2>

<h2 id="bar">bar</h2>

<div class="bd-example">
    <p>foo</p>
    <h4 id="sample-heading">Sample Heading</h4>  <!-- we don't need this -->
    
    <div class="row">
        <div class="col-md-6">
            <h5 id="nested-heading">Nested Heading</h5>
        </div>
        <div class="col-md-6">
            <h4 id="heading-would-be-tracked-again">Heading would be tracked again</h4>
            <p>lorem ipsum</p>
        </div>
    </div>
</div>

<p>sample text</p>

<h2 id="bar2">bar2</h2>

<h3 id="bar3">bar3</h3>

...which gets converted into this:

[
  '<h2 id="foo">foo</h2>',
  '<h2 id="bar">bar</h2><div class="bd-example"><p>foo</p>',
  '<h4 id="sample-heading">Sample Heading</h4><!-- we don't need this --><div class="row"><div class="col-md-6">',
  '<h5 id="nested-heading">Nested Heading</h5></div><div class="col-md-6">',
  '<h4 id="heading-would-be-tracked-again">Heading would be tracked again</h4><p>lorem ipsum</p></div></div></div><p>sample text</p>',
  '<h2 id="bar2">bar2</h2>',
  '<h3 id="bar3">bar3</h3>'
]

I'm open to clever ideas but don't think there's a sane and reliable way of handling this situation. Sorry about that!