Skip to content
/ toctoc Public

Generates and maintain a Table of Content for your README.md.

Notifications You must be signed in to change notification settings

n1k0/toctoc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 

Repository files navigation

toctoc

Generates and maintain a Table of Content for any Markdown document, especially README.md files hosted on github.

Table of Contents


Installation

Globally

$ npm install -g toctoc

Locally

$ npm install toctoc --save-dev

Setup

The program will scan the passed file contents and look for TOC placeholder, which must follow this format:

  ## Table of Contents

  ---

Note the <hr/> tag (--- in Markdown) at the end of the block.

Usage

$ toctoc README.md

By default, this command outputs the modified file contents with the TOC markdown added. You can overwrite the original file by using the -w option:

$ toctoc README.md -w

If a TOC was previously generated for this file, its previous version will be replaced with the new one.

$ toctoc docs/**/*.md -w 

You can use a glob pattern or a directory to match multiple files at once.

$ toctoc doc -w -e MD

If you use a directory, the file extensions searched is .md, if you wish to use a different file extension for markdown, use -e option.

Custom TOC heading

By default the TOC is generated using the Table of Contents heading. You can specify a custom one by using the -t option:

$ toctoc -w README.md -t="My custom TOC title"

Just ensure to update your source file to use this new heading, so the executable can find and replace the appropriate TOC section.

Max TOC depth

By default, the generated TOC will expose links to the deepest subsections of the document; to limit the maximum crawling depth, use the -d option:

$ toctoc README.md -w -d 2

Soft TOC

By default, it will fail with an error if the targeted file(s) do not have any TOC. To remove this limitation, use -s option:

$ toctoc docs/**/*.md -w -s

Directory

By default, toctoc will use a .md extension if used with a directory. You can customise the extension to be founds by passing -e option.

$ toctoc docs -w -s -e .MD

For the adventurous

It's possible to automate updating the README in a package.json prepublish command, so you're sure your npm package homepage is always updated with the right TOC when released:

  "scripts": {
    "prepublish": "./node_modules/.bin/toctoc README.md -d 2 -w"
  },

License

MIT.

About

Generates and maintain a Table of Content for your README.md.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •