Jekyll Heading Anchors without JavaScript

Despite all my efforts for developing the next major version of stakx, I come bearing gifts for the Jekyll community. When building websites with long pages, it has become the standard to include a table of contents that link to headings. Up until jekyll-toc, the only way to achieve that was through a Jekyll plugin or JavaScript. Now, the current solution for adding clickable links next to headings is to use JavaScript. Let's change that.

There are too many static websites out there that load a lot of JavaScript to the point where it slows down. Why? Seriously. Stahp that. I mean, I'm even planning on moving away from Disqus solely because it loads too much. Anyhow, websites like these cause me to navigate it with JavaScript disabled but that often leads to me not being able to click on a permalink for a heading. Taking the same behavior and concept from jekyll-toc, I've built jekyll-anchor-headings.

If things can be achieved without resorting to JavaScript, why not do it?

TL;DR Permalink to "TL;DR" section

The code is available on GitHub: allejo/jekyll-anchor-headings.

Usage Permalink to "Usage" section

Usage is simple, instead of using {{ content }} to display your page's content (your rendered markdown, i.e.) you would feed {{ content }} into the anchor_headings.html include.

{% include anchor_headings.html html=content %}

The snippet is available in the GitHub repo and has unit tests as well. We have to be sure that things continue working as expected with variations of HTML.

How it Works Permalink to "How it Works" section

Since jekyll-toc has worked out pretty robustly, I've taken a lot of the same concepts and code from that project and adapted it to work with this new project.

Step 0 Permalink to "Step 0" section

Taking steps 1 through 6 from the previous post, we currently have access to the id attribute and the contents of the actual headings (e.g. h1).

Step 1 Permalink to "Step 1" section

First, we build an anchor tag manually as a string by setting the href attribute along with class and title. So at this point, we'll have the following:

href="#some-id" class="my-class permalink" title="click me!"

Step 2 Permalink to "Step 2" section

Now, we'll take that string and simple prefix <a and append an ></a> with possibly some content in between the anchors.

Step 3 Permalink to "Step 3" section

We do some stupid string replacements to change the current heading tags (h1 - h6) with some that we build on our own with:

• The custom anchor we built in steps 1 and 2
• The heading content we have from step 0

Conclusion Permalink to "Conclusion" section

Check out the project on GitHub and give it a shot on your own website! There's no need for you to understand the craziness of manipulating HTML as strings, just {% include %} in your layouts and you're set!