toc-md

• NAME
• FEATURES
• INSTALLATION
• SYNOPSIS
• USAGE
  • CLI
    • Insert
    • Clean
  • Customizing the TOC
    • Ignoring headers
    • Changing headers
    • Renaming anchors
• COMPATIBILITY
• SEE ALSO
• VERSION
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

toc-md - a CLI tool to generate a Markdown TOC (table of contents)

FEATURES

• rename anchors with a HTML tag: <a name="new-name"></a>
• omit headers from the TOC with a HTML comment: <!-- TOC:ignore -->
• rename headers in the TOC with a HTML comment: <!-- TOC:display:New Header -->

INSTALLATION

$ npm install @chocolateboy/toc-md

SYNOPSIS

$ toc-md README.md

USAGE

Add a HTML comment <!-- TOC --> to a Markdown file.

A TOC will be generated exactly in this place for the following headers.

To migrate from an existing TOC generator with start and end markers, replace them with <!-- TOC --> and <!-- TOC END -->.

CLI

$ toc-md --help
Generates a Markdown TOC (table of contents)

Usage:
  toc-md [OPTIONS] [ARGS]

Options:
  -h, --help : Help
  -v, --version : Shows the version number
  -m MAXDEPTH, --max-depth=MAXDEPTH : Uses headings whose depth is at most the specified value (default: 6)
  -b BULLET, --bullet=BULLET : The bullet ('*', '-', '+') to use for each element in the generated TOC (default: '-')
  -c, --clean : Removes a TOC

Arguments:
  SOURCE : Path to an input Markdown file (it must contain the HTML comment <!-- TOC -->) (required)
  TARGET : Path to an output Markdown file

If the TARGET argument is not specified, the result will be written to SOURCE.

Example

Insert

$ toc-md --max-depth=4 --bullet='*' path/to/input.md path/to/output.md
$ toc-md -m 4 -b '*' path/to/input.md

Clean

$ toc-md --clean path/to/input.md path/to/output.md
$ toc-md -c path/to/input.md

Customizing the TOC

Ignoring headers

A header can be omitted from the TOC by adding a <!-- TOC:ignore --> HTML comment before a header declaration, e.g.:

<!-- TOC:ignore -->
# NPM Scripts

The NPM Scripts header will not be displayed in the TOC.

Changing headers

The name of a header in a TOC can be changed by adding a <!-- TOC:display:header_text --> HTML comment before a header declaration, e.g.:

<!-- TOC:display:Foo (Deprecated) -->
# Foo

The Foo header will be displayed in the TOC as Foo (Deprecated).

Renaming anchors

The anchor which is generated for a header can be redefined by adding an <a name="..."></a> HTML tag before a header declaration, e.g.:

<a name="foo-options"></a>
# Options

The Options header in the TOC will link to the foo-options anchor.

COMPATIBILITY

• Maintained Node.js versions

SEE ALSO

• markedpp - preprocessor for Markdown files

VERSION

0.5.1

AUTHOR

• eGavr

This is a fork of toc-md-alt by theogravity, which is a fork of toc-md by eGavr.

COPYRIGHT AND LICENSE

Copyright © 2014 by eGavr.

This is free software; you can redistribute it and/or modify it under the terms of the MIT license.