Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/n1k0/toctoc
Generates and maintain a Table of Content for your README.md.
https://github.com/n1k0/toctoc
generator markdown markup readme table-of-contents
Last synced: 6 days ago
JSON representation
Generates and maintain a Table of Content for your README.md.
- Host: GitHub
- URL: https://github.com/n1k0/toctoc
- Owner: n1k0
- Created: 2016-03-16T13:10:44.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-05-02T09:25:46.000Z (over 3 years ago)
- Last Synced: 2024-10-19T10:33:04.647Z (27 days ago)
- Topics: generator, markdown, markup, readme, table-of-contents
- Language: JavaScript
- Size: 30.3 KB
- Stars: 16
- Watchers: 4
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
toctoc
======
Generates and maintain a Table of Content for any Markdown document, especially `README.md` files hosted on github.
## Table of Contents
- [Installation](#installation)
- [Globally](#globally)
- [Locally](#locally)
- [Setup](#setup)
- [Usage](#usage)
- [Custom TOC heading](#custom-toc-heading)
- [Max TOC depth](#max-toc-depth)
- [Soft TOC](#soft-toc)
- [Directory](#directory)
- [For the adventurous](#for-the-adventurous)
- [License](#license)
---
## 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:
```markdown
## Table of Contents
---
```
Note the `
` 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](http://pubs.opengroup.org/onlinepubs/9699919799/functions/glob.html) 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:
```json
"scripts": {
"prepublish": "./node_modules/.bin/toctoc README.md -d 2 -w"
},
```
## License
MIT.