Anchorific.js

What is it?

Anchorific automatically generates anchored headings and nested navigations based on header tags. Anchored links ( # ) on this page and the nested navigation on the left is generated automatically by Anchorific.js.

Why?

I always create single-page project documentations with anchored headings and anchored-based navigations to jump from one section to another. However, I feel that it is repetitive to create the anchored headings and anchored-based navigations manually. I want to focus on writing the documentation and let jQuery generates the anchored headings and nested navigations for me. Thus, Anchorific.js was born.

There is also another main reason why. You can check it out here on renaysha.me/2013/10/anchorific-js-now-on-github/

Getting Started

HTML Structure

Be mindful of how you structure the header tag. H1 should be followed by H2, H2 should be followed by H3 and so on. You should not skip a level with the header tags.

Anchorific relies heavily on this particular structure when generating the anchor navigation. For a quick help, you can see how this page’s header tags is structured.

<h1>The Lannisters</h1>
    <h2>Tywin Lanister</h2>
    <h2>Cersei Lannister</h2>
        <h3>Joffrey Baratheon</h3>
        <h3>Myrcella Baratheon</h3>
        <h3>Tommen Baratheon</h3>
    <h2>Jaime Lannister</h2>
    <h2>Tyrion Lannister</h2>

The plugin will create anchored headings and add an anchor link within the header tag:

<h1>Tywin Lannister</h1>
<!-- This would be turn to -->
<h1 id="tywin-lannister">Tywin Lannister <a href="#tywin-lannister" class="anchor">#</a></h1>

What about existing ID?

It is okay to have an existing ID on your header tag, such as this one above! You can have something like this:

<h3 id="what-if-I-already-have-an-id">What about existing ID?</h3>
<!-- This would be turn to -->
<h3 id="what-if-I-already-have-an-id">What about existing ID?<a href="#what-if-I-already-have-an-id" class="anchor">#</a></h3>

Anchorific.js preserves the original ID and also uses the original ID value on the anchor’s href attribute.

Generate navigations

Include a div or a nav section where you want the unordered list of anchor navigation to be appended at:

<nav class='anchorific'></nav>

By default, the plugin will append the unordered list under an element with class called anchorific. If you wish to use another class name, you need to specify it in the plugin’s option.

CSS

The anchored navigation can be styled easily. As stated previously, the anchored navigation will be appended under a class named anchorific. Below are the selector that you can use in your CSS in order to style the anchored navigation.

.anchorific {}
.anchorific ul {}
.anchorific ul li a {}
.anchorific li ul {}
.anchorific li.active > a {}
.anchorific li.active > ul {}
        

You can also check this page’s CSS in order to see how it is done. The anchored navigation for this page is inspired by the ones used in getbootstrap.com.

Basic Usage & Options

This documentation used the following usage below since we only want to include the header tag inside the content wrapper:

$('.content').anchorific();

You can call the plugin function with any selector you want as long as it adhere to the HTML structure mentioned above. Options available are as followed:

$('.content').anchorific({
    navigation: '.anchorific', // position of navigation
	speed: 200, // speed of sliding back to top
	anchorClass: 'anchor', // class of anchor links
	anchorText: '#', // prepended or appended to anchor headings
	top: '.top', // back to top button or link class
	spy: true, // highlight active links as you scroll
	position: 'append' // position of anchor text
});

Generating navigations, Scroll spy, and ‘Back to top’ functionality can be disable by assigning false value to the options.

Adding ‘Back to Top’ Button

The ‘Back to Top’ button can be added easily. Just add an element with class top. You can use other class names but it should be specified in the plugin options.

 <a href="#top" class="top">Scroll to top</a>

Remember to add display: none; to the .top styling. It should not be visible when the page first load.

The speed of the scrolling effect can be adjusted by specifying it in the options above.

If you do not wish to have a ‘back to top’ button, you can disable the functionality by assigning the top option to false.

Demo?

You’re looking at it! ‘Right click > Inspect element’ to any of the header tags above in order to see how the anchored headings are generated.

The navigation on the left shows how the nested navigations are generated. Note that the plugin just adds an ‘active’ class when scrolling. You can manipulate the effects using CSS.

There is also a ‘back to top’ button on the lower right.

The plugins are thoroughly tested with Qunit.js. I have tested the navigations generated from h1 – h6 tags. If you want to see how that looks like, just view the index.html page on the project’s folder or by running the test. If you have Grunt.js installed, you can just cd to the folder and run npm install. After that is done, just type grunt in your terminal.

It is also possible to just run the test through the index.html file in the tests folder. However, you need to use a local server like MAMP or node.js in order to run the file as I used iFrame in order to test the scrolling event.

Thoughts?

Back to top

  • Pingback: Anchorific.js is now on Github! | Ren Aysha()

  • Pingback: Testing Scrolling Events with Qunit.js | Ren Aysha()

  • Seriously, this looks amazing. Insanely solid work on this Ren. Been looking for this exact plugin from time to time for years.

    • Thanks so much for the kind words, Cory. I am glad that you like it 🙂

  • Alex Yehorov

    Well done, indeed. I was wondering if there’s a way for the first element to have the “active” class by default without the need to scroll first?

    • I believe you can achieve this by giving the first element an active class straight away; you do not really need to set it through the plugin. The scroll spy should work normally as well. Let me know if it works.

  • Bevan Lloyd Von Weichardt

    AWESOME!!! Any way to make this work as a Joomla Module?

    • Well, I have never use Joomla. I am not familiar with its module architecture. Perhaps you would be so kind and make it work for Joomla?

      This is a jQuery plugin though. I am not sure about Joomla’s architecture but the purpose of jQuery plugin is to make it easier to plug n’ play. Unless if you are thinking of something more advance that the current functionality of Anchorific.

    • David Weller

      jquery is included in the joomla core now. You should be able to just find the file in your theme that will take javascript code and add it in, if your Joomla version is current

  • ds936

    Great plugin! Anyone using cyrillic chars, replace the “[^ws]/gi” chunk with “[^wsа-я]/gi” – worked for me.

  • David Weller

    This is cool. Is there a way to keep the sub-level tags always visible?

    • Anchorific’s styling is controlled by CSS. So, if you want to keep the sub-level tags visible, you can just set the property display to block for the sub-level tags: “display: block”. Currently, my sub-level tags are set to: “display: none”.

      • David Weller

        Thank you so much. Giving it a test run tonight.

  • SCKD

    This is pretty awesome for sure 🙂 I have this up live now on one page, and am considering using it on a bunch of other staff generated pages, since they don’t have to worry about id’s and all that jazz with this. One question though; is there some way I can only have it looking at a certain level of heading, for example, only convert h3’s, or only h4’s etc? I guess I could hide all h4’s as you note in the below comment using CSS, but perhaps there would be a performance win not taking all into account as well?

    • I am not sure if this feature is already implemented. If it has, calling $(‘h3, h4’).anchorific() should work. Otherwise, it will be a nice feature to have.

  • Wow, amazing! Just what I was looking for! This will save me so much time on my blog.

  • Supercalifragilisticexpialidocious! You made my day :).
    Just tried it on a static page, generated from a project’s README.md, and “it works”, as used to say an Apache friend of mine (sorry for geeky humor :/).
    Really nice anyway, thanks for sharing your work, and keep going!

  • Joachim Richter

    Hi Aysha,
    doesn’t work on firefox 🙁
    all the best from the canary islands

    • What is the bug exactly? Be specific.