metalsmith-doctoc-cheerio

This metalsmith-doctoc (npmjs, github) plugin will use cheerio (npmjs, github) to read the heading tags from any HTML content. It will process fully specified HTML documents, or a mere tag soup (e.g. no html, head or body tags).

Cheerio itself will use htmlparser2 (npmjs, github) to read HTML/XML content.

Installation

npm install metalsmith-doctoc-cheerio

Options object

This plugin will accept the following option properties:

Options {
  //- these are htmlparser2 specific options:
  //  https://github.com/fb55/htmlparser2/wiki/Parser-options
  //- cheerio will pass this options object on to its
  //  underlying htmlparser2 instance.
  htmlparser2: {
    //- enable to give <script> and <style> special treatment
    xmlMode: false,
    //- enable to decode entities within the document
    decodeEntities: false,
    //- enable to lowercase all tags if xmlMode is disabled
    //- if false, lowercase tags will remain lowercase,
    //  but uppercase attribute names will be lowercased!
    lowerCaseTags: false,
    //- enable to recognize CDATA sections as text,
    //  even if xmlMode is disabled
    //- implicitly enabled if xmlMode is true
    recognizeCDATA: false,
    //- enable to trigger the onclosetag event
    //  if xmlMode is disabled
    //- implicitly enabled if xmlMode is true
    recognizeSelfClosing: false
  }
  
  //- $range = 'h$min-$max'
  //- with $min and $max in [1,6] and ($min <= $max)
  //- $min will replace hMin and $max will replace hMax
  hRange: "h1-6",
  
  //- an integer value in [1,6]
  //- if hMin=X, then this plugin will
  //  ignore any heading tag <hN> if (N < X)
  //- if (hMin == hMax == X), then this plugin will
  //  ignore any heading tag, but not <hX>
  //- if (hMin > hMax), then all heading tags will be ignored!
  hMin: 1,

  //- an integer value in [1,6]
  //- if hMax=X, then this plugin will
  //  ignore any heading tag <hN> if (N > X)
  //- if (hMin == hMax == X), then this plugin will
  //  ignore any heading tag, but not <hX>
  //- if (hMin > hMax), then all heading tags will be ignored!
  hMax: 6,

  //- $selector = /h[1-6](,\s*h[1-6])*/
  //- a heading will only be taken into account, if it's tag
  //  can be found inside hSelector
  //- if hRange is given, it will override hMin and hMax
  //- if hMin or hMax are given, they will override hSelector
  //- hSelector is what will be used to find the heading tags
  hSelector: 'h1, h2, h3, h4, h5, h6',
  
  //- use this value to specify a cheerio context in which to
  //  look for heading tags.
  //- e.g. use '*' to search the whole document
  //- e.g. use '#id' to only search the element marked with the
  //  specified id value.
  hContext: '*',
  
  //- string function(string)
  //- this function will be used to calculate a missing id:
  //  assuming "<h1>$title</h1>" was found, an id will be
  //  generated as follows: $id = options.slugFunc($title)
  //- the purpose of this function is to generate an id
  //  value that respects HTML's requirements for these
  //  kind of values; e.g. no (') or (") characters, etc.
  //- node's slug module isn't flawless:
  //  slug('1.') === slug('1..') === '1'
  //  i.e. a possible id value collision
  //- this option allows you to specify a function of your
  //  own in case slug() causes any issues
  slugFunc: slug,

  //- if a heading of the form <h1>$title</h1> is found, an id
  //  will be generated using '$id = slug($title)'. in order to
  //  avoid collision of id values, generated ids will be
  //  prefixed with $idPrefix;
  //  i.e. '<h1 id="$idPrefix$id">$title</h1>'.
  //- set to "" if you don't want to use a prefix.
  idPrefix: "doctoc-",

  //- this will limit id = (idPrefix + slugFunc(title))
  //  to the specified number of characters.
  //- id values might exceed that limit by some unique
  //  number suffix.
  idLengthLimit: 256

  //- if set to true, this will do check that a generated id is
  //  not already in use. so a test will be done for each
  //  id generated!
  //- if such a test determines that a generated value is not
  //  unique, append a counter (=1) to the id's value,
  //  i.e. '$newId=$id-$counter'. redo the test with the new
  //  value. if $newId still isn't unique, increment the
  //  counter and repeat the procedure.
  makeIdsUnique: false,

  //- set true to always update file.contents;
  //  even if no new id was generated
  alwaysUpdate: false
}

Note that if a hRange value is given, it will override hMin, hMax and hSelector. And if hRange is omitted, but hMin and/or hMax are given, they will override hSelector. So only one of those (hRange, hMin/hMax or hSelector) should be used.

Note that tag selection via hSelector is case-sensitive! If a document contains h2 and H2 tags, then hSelector must reflect this, or some headings will be ignored. If a hSelector is generated (from hRange, hMin, hMax), it will contain lowercase and uppercase tags.

Range/Selector for options

This plugin will accept a range string instead of an options object:

metalsmith-doctoc-options {
  ...
  plugins: {
    ...
    $configName: {
      ... options: 'h1-6' ...
    }
    ...
  },
  ...
}

It is also possible to provide a selector string:

... options: 'h1, h2, h3, h4' ...

Node.heading objects

These objects will have the following properties:

Heading {
  //- e.g. 'h1' in case of '<h1>'
  tag: $tag,

  //- e.g. '$id' in case of '<h1 id="$id">'
  id: $id,

  //- e.g. '$title' in case of '<h1>$title</h1>'
  title: $title,

  //- e.g. 2 in case of '<h2>'
  level: $level
}