npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

anchorific

v0.1.3

Published

Automatically generate anchored headings and nested navigations based on header tags

Downloads

50

Readme

Anchorific.js

Anchorific is a jQuery plugin that automatically generates anchored headings and nested navigations based on header tags. My intention is for it to be used in single-page project documentation. Project page and demo here: https://anchorific.netlify.app/

Installation

Via NPM

npm install --save anchorific

For a guide on how to using jQuery plugins with npm, check out: https://blog.npmjs.org/post/112064849860/using-jquery-plugins-with-npm

Via CDN

<script src="https://cdnjs.cloudflare.com/ajax/libs/anchorific/1.2/min/anchorific.min.js"></script>

Getting Started

HTML Structure

You should not skip a level when structuring header tags. H1 should be followed by H2, H2 should be followed by H3 and so on. Anchorific relies heavily on this particular structure when generating the anchor navigation.

<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>

Based on the HTML markup above, the plugin will generate nested navigations like this one:

<ul>
  <li data-tag="1">
    <a href="#the-lannisters">The Lannisters</a>
    <ul>
      <li data-tag="2"><a href="#tywin-lannister">Tywin Lannister</a></li>
      <li data-tag="2">
        <a href="#cersei-lannister">Cersei Lannister</a>
        <ul>
          <li data-tag="3">
            <a href="#joffrey-baratheon">Joffrey Baratheon</a>
          </li>
          <li data-tag="3">
            <a href="#myrcella-baratheon">Myrcella Baratheon</a>
          </li>
          <li data-tag="3"><a href="#tommen-baratheon">Tommen Baratheon</a></li>
        </ul>
      </li>
      <li data-tag="2"><a href="#jaime-lannister">Jaime Lannister</a></li>
      <li data-tag="2"><a href="#tyrion-lannister">Tyrion Lannister</a></li>
    </ul>
  </li>
</ul>

...and it will generate anchored headings like this one:

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

Existing ID

Any existing ID will be preserved by the plugin:

<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>

Generate Navigation

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 nested navigation can be styled easily. Below are the selectors you can use in order to style the generated navigation.

.anchorific {
}
.anchorific ul {
}
.anchorific ul li a {
}
.anchorific li ul {
}
/* active class is generated by the scrollspy */
.anchorific li.active > a {
}
.anchorific li.active > ul {
}

You can also check the demo page's CSS to see how it is done.

Basic Usage and Options

Use the selector where your headings are located under. And then just call the anchorific method.

$('.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
  headers: 'h1, h2, h3, h4, h5, h6', // headers that you wish to target
  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, // scroll spy
  position: 'append', // position of anchor text
  spyOffset: 0, // specify heading offset for spy scrolling
  navElements: [], // if there are other elements that should act as navigation, add classes here
});

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

Adding 'Back to Top' Button

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>

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

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

Build

Anchorific.js good old npm scripts to run test and build the code.

Run test:

$ npm test

Build code:

$ npm run build

Setup

CD to the project folder and type:

$ npm install

Run test

npm test

Contributing

In order to contribute, open a pull request and ensure that new tests are written in order to test out your contributions. Ensure that previous test pass by running npm test. Running /tests/index.html directly in the browser will show you some failed tests but this is because those tests are testing the scroll functionality which it doesn't support. Running npm test is more reliable.

License

MIT License