Neurotic Programmer Masquerade

    marked-toc

    0.3.0 • Public • Published

    marked-toc NPM version

    Generate a TOC (table of contents) for markdown files

    (example)

    Getting Started

    Install the module with npm:

    npm i -g marked-toc --save

    In any markdown file, add <!-- toc --> where you want to add the TOC. Then in the command line, run:

    toc [filename]

    If you add the toc to a README.md, no need to add [filename], just run toc.

    Usage

    var toc = require('marked-toc');
    var file = fs.readFileSync('README.md', 'utf8');
     
    // Generate a TOC
    toc(file);

    Options

    All methods accept an object of options as the last argument.

    template

    Type: String

    Default: <%= depth %><%= bullet %>[<%= heading %>](#<%= url %>)\n

    The Lo-Dash template used to generate the Table of Contents.

    Example (this is the default):

    var tmpl = '<%= depth %><%= bullet %>[<%= heading %>](#<%= url %>)\n';
    toc(file, {template: tmpl});

    bullet

    Type: String|Array

    Default: *

    The bullet to use for each item in the generated TOC. This is passed as a variable to the <%= bullet %> template.

    If an array, like ['* ', '- '], the bullet point strings will be used based on the header depth.

    maxDepth

    Type: Number

    Default: 3

    Use headings whose depth is at most maxDepth.

    firsth1

    Type: Boolean

    Default: False

    Include the first h1-level heading in a file. For example, this prevent the first heading in a README from showing up in the TOC.

    omit

    Type: Array

    Default: ['Table of Contents', 'TOC', 'TABLE OF CONTENTS']

    Omit entire headings from the TOC if they have these strings.

    clean

    Type: Array

    Default: ['mixin', 'helper', 'filter']

    Strip "blacklisted" keywords from the headings.

    Example:

    toc(file, {clean: ['docs', 'methods']});

    converts this:

    ## docs-foo
    Foo
     
    ## methods-bar
    Bar
     

    to:

    * [foo](#docs-foo)
    * [bar](#methods-bar)
     

    blacklist

    Type: Boolean

    Default: true

    An array of strings used the omit option:

    ['grunt', 'helper', 'handlebars-helper', 'mixin', 'filter', 'assemble-contrib', 'assemble']

    (These strings are used a lot in documentation headings, but (usually) shouldn't show up in the gererated TOC.)

    allowedChars

    Type: String

    Default: -

    String of chars that you want to be whitelisted when headings are "slugified" for links, e.g. -_~.

    Example:

    // This heading
    Getting Started
     
    // Converts to this link
    * [Getting Started](#getting-started)
     

    API

    Most methods expect a string as the first paramter, so unless otherwise noted, assume that each example gets the str variable from:

    var str = fs.readFileSync('README.md', 'utf8')

    toc

    Generates a Table of Contents from a string.

    // Generate a TOC
    var table = toc(str);
    fs.writeFileSync('toc.md', table);

    toc.insert

    Inject a TOC at the insertion point in a string, <!-- toc -->.

    Params:

    • str: the content
    • options: object of options
    toc.insert(str, options);

    toc.add

    1. Read a file and inject a TOC at the specified insertion point, <!-- toc -->,
    2. Write the file to the specified dest, (or re-write back to the source file if no dest is passed)
    toc.add(src, dest, options)

    Example:

    toc.add('path/to/source.md', 'path/to/dest.md');

    Source only:

    toc.add('README.md');

    toc.raw

    Output a "raw" (JSON) Table of Contents object, for customization and usage in templates

    toc.raw(str, options);

    Returns an object (JSON) with two properties, data and toc:

    • data: array of headings and associated properties used to construct a TOC. TIP: this can be extended with properties, such as src path etc.
    • toc: the actual Table of Contents result, as a string

    Example:

    {
      // Array of
      "data": [
        {
          "depth": "",
          "bullet": "",
          "heading": "Getting Started",
          "url": "getting-started"
        },
        {
          "depth": "",
          "bullet": "",
          "heading": "Usage",
          "url": "usage"
        }
      ],
     
      // String. the actual TOC
      "toc": "* [Getting Started](#getting-started)\n* [Options](#options)\n* [Contributing](#contributing)\n"
    }

    See an example.

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint your code using jshint and run tests with mocha -R spec before making a pull request.

    Author

    License

    Copyright (c) 2014 Jon Schlinkert, contributors Licensed under the MIT license.

    Install

    npm i marked-toc

    DownloadsWeekly Downloads

    255

    Version

    0.3.0

    License

    none

    Last publish

    Collaborators

    • jonschlinkert
    • doowb