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

contents

v5.0.0

Published

Table of contents generator.

Downloads

2,527

Readme

Table of Contents (TOC) Generator

Travis build status NPM version

Table of contents generator.

Usage

Quick Start

import Contents from 'contents';

// This example generates a table of contents for all of the headings in the document.
// Table of contents is an ordered list element.
const contents = Contents();

// Append the generated list element (table of contents) to the container.
document.querySelector('#your-table-of-contents-container').appendChild(contents.list());

// Attach event listeners:
contents.eventEmitter().on('change', function () {
  console.log('User has navigated to a new section of the page.');
});

// The rest of the code illustrates firing "resize" event after you have
// added new content after generating the table of contents.
const newHeading = document.createElement('h2');

hewHeading.innerHTML = 'Dynamically generated title';

document.body.appendChild(newHeading);

// Firing the "resize" event will regenerate the table of contents.
contents.eventEmitter().trigger('resize');

Examples

The code for all of the examples is in the examples folder.

Raise an issue if you are missing an example.

Introduction of ES6 in 4.0.0

Similar Libraries stats have been generated in 22-Nov-14 08:44:41 UTC. Since then Contents has evolved a lot. The source code is written in ES6 and depends on babel-core to run. In projects that already depend on Babel and use webpack to build packages, this is not going to be a problem. Other projects need to consider the relatively heavy weight of the generated package.

Similar Libraries

| Feature | contents | toc | jquery.tocify.js | | --- | --- | --- | --- | | Markup using nested <ol> | ✓ | - | - | | Smooth scrolling | - | ✓ | ✓ | | Forward and back button support | ✓ | - | ✓ | | Events | ✓ | - | - | | Efficient scroll event | ✓ | ✓ | - | | Reflect window resize | ✓ | - | ✓ | | Extract table of contents as an array | ✓ | - | - | | Overwrite markup and navigation | ✓ | - | - | | Can have multiple on a page | ✓ | ✓ | ✓ | | Required 3rd party libraries | - | jQuery | jQuery, jQueryUI | | Size | < 6.000 kb | 2.581 kb | 7.246 kb | | GitHub Stars | 192 | 307 | 435 |

Last updated: Saturday, 22-Nov-14 08:44:41 UTC.

Required 3rd Party Libraries

There are no 3rd party dependencies. jQuery selectors are used in the examples to make it simple for the reader.

Smooth Scrolling

You can implement smooth scrolling using either of the existing libraries. See Integration Examples.

Window Resize and scroll Event Handling

The library will index offsetTop of all articles. This index is used to reflect the change event. The index is built upon loading the page, and in response to window.onresize and ready events.

Reading offsetTop causes a reflow. Therefore, this should not be done while scrolling.

Table of Contents Array

You can extract the table of contents as a collection of nested objects representing the table of contents.

/**
 * @return {array} Array representation of the table of contents.
 */
contents.tree();

Tree is a collection of nodes:

[
  // Node
  {
    // Hierarchy level (e.g. h1 = 1)
    level: 1,
    // Id derived using articleId() function.
    id: '',
    // Name derived using articleName() function.
    name: '',
    // The article element.
    element: null,
    // Collection of the descendant nodes.
    descendants: [ /* node */ ]
  }
]

Download

Using NPM:

npm install contents

Configuration

| Name | Type | Description | | --- | --- | --- | | articles | NodeList, jQuery | (optional) The default behavior is to index all headings (H1-H6) in the document. See Content Indexing. | | link | function | (optional) Used to represent article in the table of contents and to setup navigation. See Linking. |

Content Indexing

The default behavior is to index all headings (H1-H6) in the document.

Use articles setting to index content using your own selector:

Contents({
  articles: document.querySelectorAll('main h2, main h2')
  // If you are using jQuery
  // articles: $('main').find('h2, h3').get()
});

Hierarchy

articles will be used to make the table of contents. articles have level of importance. The level of importance determines list nesting (see Markup). For HTML headings, the level of importance is derived from the tag name (<h[1-6]>). To set your own level of importance, use Contents.level dataset property or jQuery data property with the same name, e.g.

$('main').find('.summary').data('gajus.contents.level', 4);

Contents({
  articles: $('main').find('h1, h2, h3, .summary').get()
});

When level of importance cannot be determined, it defaults to 1.

Linking

link method is used to represent article in the table of contents and to setup navigation. This method is called once for each article after the list of the table of contents is generated.

The default implementation:

  1. Derives ID from the article
  2. Generates a hyperlink using article ID as the anchor
  3. Appends the URL to the table of contents
  4. Wraps the article node in a self-referencing hyperlink.
/**
 * This function is called after the table of contents is generated.
 * It is called for each article in the index.
 * Used to represent article in the table of contents and to setup navigation.
 *
 * @param {HTMLElement} guide An element in the table of contents representing an article.
 * @param {HTMLElement} article The represented content element.
 */
Contents.link = (guide, article) => {
  const guideLink = document.createElement('a'),
  const articleLink = document.createElement('a'),
  const articleName = article.innerText,
  const articleId = article.id || Contents.id(articleName);

  article.id = articleId;

  articleLink.href = '#' + articleId;

  while (article.childNodes.length) {
    articleLink.appendChild(article.childNodes[0], articleLink);
  }

  article.appendChild(articleLink);

  guideLink.appendChild(document.createTextNode(articleName));
  guideLink.href = '#' + articleId;
  guide.insertBefore(guideLink, guide.firstChild);
};

To overwrite the default behavior, you can provide your own link function as part of the configuration:

Contents({
  // Example of implementation that does not wrap
  // article node in a hyperlink.
  link: (guide, article) => {
    var guideLink,
        articleName,
        articleId;

    guide = $(guide);
    article = $(article);

    guideLink = $('<a>');
    articleName = article.text();
    articleId = article.attr('id') || Contents.id(articleName);

    guideLink
      .text(articleName)
      .attr('href', '#' + articleId)
      .prependTo(guide);

    article.attr('id', articleId);
  }
});

Article ID

The default implementation relies on each article having an "id" attribute to enable anchor navigation.

If you are overwriting the default link implementation, you can take advantage of the Contents.id function.

Contents.id is responsible for deriving a unique ID from the text of the article, e.g.

<h2>Allow me to reiterate</h2>
<h2>Allow me to reiterate</h2>
<h2>Allow me to reiterate</h2>

The default link implementation will use Contents.id to give each article a unique ID:

<h2 id="allow-me-to-reiterate">Allow me to reiterate</h2>
<h2 id="allow-me-to-reiterate-1">Allow me to reiterate</h2>
<h2 id="allow-me-to-reiterate-2">Allow me to reiterate</h2>

Markup

Table of contents is an ordered list element. List nesting reflects the heading hierarchy. The default behavior is to represent each heading using a hyperlink (See Linking), e.g.

<h1>JavaScript</h1>
<h2>History</h2>
<h2>Trademark</h2>
<h2>Features</h2>
<h3>Imperative and structured</h3>
<h3>Dynamic</h3>
<h3>Functional</h3>
<h2>Syntax</h2>

Contents will generate the following markup for the above content:

<ol>
  <li>
    <a href="#javascript">JavaScript</a>

    <ol>
      <li>
        <a href="#history">History</a>
      </li>
      <li>
        <a href="#trademark">Trademark</a>
      </li>
      <li>
        <a href="#features">Features</a>

        <ol>
          <li>
            <a href="#imperative-and-structured">Imperative and structured</a>
          </li>
          <li>
            <a href="#dynamic">Dynamic</a>
          </li>
          <li>
            <a href="#functional">Functional</a>
          </li>
        </ol>
      </li>
      <li>
        <a href="#syntax">Syntax</a>
      </li>
    </ol>
  </li>
</ol>

Events

| Event | Description | | --- | --- | | ready | Fired once after the table of contents has been generated. | | resize | Fired when the page is loaded and in response to "resize" and "orientationchange" window events. | | change | Fired when the page is loaded and when user navigates to a new section of the page. |

Attach event listeners using the eventEmitter.on of the resulting Contents object:

const contents = Contents();

contents.eventEmitter.on('ready', () => {});
contents.eventEmitter.on('resize', () => {});

The change event listener is passed extra parameters: .current.article, .current.guide, and when available, .previous.article, .previous.guide:

contents.eventEmitter.on('change', (data) => {
  if (data.previous) {
    $(data.previous.article).removeClass('active-article');
    $(data.previous.guide).removeClass('active-guide');
  }

  $(data.current.article).addClass('active-article');
  $(data.current.guide).addClass('active-guide');
});

You must trigger "resize" event after programmatically changing the content or the presentation of the content.:

contents.eventEmitter.trigger('resize');

This is required to recalculate the position of the content.