diff --git a/.verb.md b/.verb.md index bdd7611..72918e5 100644 --- a/.verb.md +++ b/.verb.md @@ -17,6 +17,9 @@ Usage: markdown-toc [options] --json: Print the TOC in JSON format + --check: Check whether the TOC is up to date. Print the result to stdout and + exit with status 1 if the TOC is outdated. + --append: Append a string to the end of the TOC --bullets: Bullets to use for items in the generated TOC diff --git a/README.md b/README.md index b8766c4..2907179 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,9 @@ -# markdown-toc [![NPM version](https://img.shields.io/npm/v/markdown-toc.svg?style=flat)](https://www.npmjs.com/package/markdown-toc) [![NPM monthly downloads](https://img.shields.io/npm/dm/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc) [![NPM total downloads](https://img.shields.io/npm/dt/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/markdown-toc.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/markdown-toc) [![Windows Build Status](https://img.shields.io/appveyor/ci/jonschlinkert/markdown-toc.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/jonschlinkert/markdown-toc) +# markdown-toc [![NPM version](https://img.shields.io/npm/v/markdown-toc.svg?style=flat)](https://www.npmjs.com/package/markdown-toc) [![NPM monthly downloads](https://img.shields.io/npm/dm/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc) [![NPM total downloads](https://img.shields.io/npm/dt/markdown-toc.svg?style=flat)](https://npmjs.org/package/markdown-toc) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/markdown-toc.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/markdown-toc) [![Windows Build Status](https://img.shields.io/appveyor/ci/jonschlinkert/markdown-toc.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/jonschlinkert/markdown-toc) > Generate a markdown TOC (table of contents) with Remarkable. -## Table of Contents +Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support. -- [Install](#install) -- [CLI](#cli) - [Highlights](#highlights) - [Usage](#usage) - [API](#api) @@ -33,6 +31,14 @@ Install with [npm](https://www.npmjs.com/): $ npm install --save markdown-toc ``` +## Quick Start + +Assuming you want to add a TOC to README.md: + +1. `$ npm install -g markdown-toc` +2. Edit README.md and insert the following line where you want the TOC inserted:
`` +3. `$ markdown-toc -i README.md` + ## CLI ``` @@ -41,11 +47,31 @@ Usage: markdown-toc [options] input: The Markdown file to parse for table of contents, or "-" to read from stdin. - -i: Edit the file directly, injecting the TOC at ; + -i: Edit the file directly, injecting the TOC at - [Highlights](#highlights) +- [Usage](#usage) +- [API](#api) + * [toc.plugin](#tocplugin) + * [toc.json](#tocjson) + * [toc.insert](#tocinsert) + * [Utility functions](#utility-functions) +- [Options](#options) + * [options.append](#optionsappend) + * [options.filter](#optionsfilter) + * [options.slugify](#optionsslugify) + * [options.bullets](#optionsbullets) + * [options.maxdepth](#optionsmaxdepth) + * [options.firsth1](#optionsfirsth1) + * [options.stripHeadingTags](#optionsstripheadingtags) +- [About](#about) + +_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_; (Without this flag, the default is to print the TOC to stdout.) --json: Print the TOC in JSON format + --check: Check whether the TOC is up to date. Print the result to stdout and + exit with status 1 if the TOC is outdated. + --append: Append a string to the end of the TOC --bullets: Bullets to use for items in the generated TOC @@ -59,6 +85,9 @@ Usage: markdown-toc [options] --no-stripHeadingTags: Do not strip extraneous HTML tags from heading text before slugifying + + --indent: Provide the indentation to use - defaults to ' ' + (to specify a tab, use the bash-escaped $'\t') ``` ## Highlights @@ -287,73 +316,89 @@ Strip extraneous HTML tags from heading text before slugifying. This is similar ## About +
+Contributing + +Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). + +
+ +
+Running Tests + +Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: + +```sh +$ npm install && npm test +``` + +
+ +
+Building docs + +_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ + +To generate the readme, run the following command: + +```sh +$ npm install -g verbose/verb#dev verb-generate-readme && verb +``` + +
+ ### Related projects +You might also be interested in these projects: + * [gfm-code-blocks](https://www.npmjs.com/package/gfm-code-blocks): Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string. | [homepage](https://github.com/jonschlinkert/gfm-code-blocks "Extract gfm (GitHub Flavored Markdown) fenced code blocks from a string.") * [markdown-link](https://www.npmjs.com/package/markdown-link): Micro util for generating a single markdown link. | [homepage](https://github.com/jonschlinkert/markdown-link "Micro util for generating a single markdown link.") -* [markdown-utils](https://www.npmjs.com/package/markdown-utils): Micro-utils for creating markdown snippets. | [homepage](https://github.com/jonschlinkert/markdown-utils "Micro-utils for creating markdown snippets.") +* [markdown-utils](https://www.npmjs.com/package/markdown-utils): Tiny helpers for creating consistenly-formatted markdown snippets. | [homepage](https://github.com/jonschlinkert/markdown-utils "Tiny helpers for creating consistenly-formatted markdown snippets.") * [pretty-remarkable](https://www.npmjs.com/package/pretty-remarkable): Plugin for prettifying markdown with Remarkable using custom renderer rules. | [homepage](https://github.com/jonschlinkert/pretty-remarkable "Plugin for prettifying markdown with Remarkable using custom renderer rules.") * [remarkable](https://www.npmjs.com/package/remarkable): Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in… [more](https://github.com/jonschlinkert/remarkable) | [homepage](https://github.com/jonschlinkert/remarkable "Markdown parser, done right. 100% Commonmark support, extensions, syntax plugins, high speed - all in one.") -### Contributing - -Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). - ### Contributors | **Commits** | **Contributor** | | --- | --- | -| 196 | [jonschlinkert](https://github.com/jonschlinkert) | +| 197 | [jonschlinkert](https://github.com/jonschlinkert) | +| 9 | [doowb](https://github.com/doowb) | +| 4 | [dbooth-boston](https://github.com/dbooth-boston) | | 4 | [stefanwalther](https://github.com/stefanwalther) | +| 3 | [sapegin](https://github.com/sapegin) | | 3 | [Marsup](https://github.com/Marsup) | | 2 | [dvcrn](https://github.com/dvcrn) | | 2 | [maxogden](https://github.com/maxogden) | | 2 | [twang2218](https://github.com/twang2218) | -| 2 | [angrykoala](https://github.com/angrykoala) | | 2 | [zeke](https://github.com/zeke) | | 1 | [Vortex375](https://github.com/Vortex375) | -| 1 | [owzim](https://github.com/owzim) | | 1 | [chendaniely](https://github.com/chendaniely) | | 1 | [Daniel-Mietchen](https://github.com/Daniel-Mietchen) | | 1 | [Feder1co5oave](https://github.com/Feder1co5oave) | | 1 | [garygreen](https://github.com/garygreen) | | 1 | [TehShrike](https://github.com/TehShrike) | | 1 | [citizenmatt](https://github.com/citizenmatt) | +| 1 | [mgroenhoff](https://github.com/mgroenhoff) | | 1 | [rafaelsteil](https://github.com/rafaelsteil) | | 1 | [RichardBradley](https://github.com/RichardBradley) | | 1 | [sethvincent](https://github.com/sethvincent) | +| 1 | [shanehughes3](https://github.com/shanehughes3) | +| 1 | [bcho](https://github.com/bcho) | | 1 | [lu22do](https://github.com/lu22do) | -### Building docs - -_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ - -To generate the readme, run the following command: - -```sh -$ npm install -g verbose/verb#dev verb-generate-readme && verb -``` - -### Running tests - -Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: - -```sh -$ npm install && npm test -``` - ### Author **Jon Schlinkert** -* [github/jonschlinkert](https://github.com/jonschlinkert) -* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) +* [GitHub Profile](https://github.com/jonschlinkert) +* [Twitter Profile](https://twitter.com/jonschlinkert) +* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert) ### License -Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). +Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert). Released under the [MIT License](LICENSE). *** -_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on September 19, 2017._ \ No newline at end of file +_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on August 13, 2019._ \ No newline at end of file diff --git a/cli.js b/cli.js index 87dd4c0..80ae873 100755 --- a/cli.js +++ b/cli.js @@ -4,7 +4,7 @@ var fs = require('fs'); var toc = require('./index.js'); var utils = require('./lib/utils'); var args = utils.minimist(process.argv.slice(2), { - boolean: ['i', 'json', 'firsth1', 'stripHeadingTags'], + boolean: ['i', 'json', 'check', 'firsth1', 'stripHeadingTags'], string: ['append', 'bullets', 'indent'], default: { firsth1: true, @@ -24,6 +24,9 @@ if (args._.length !== 1) { '', ' --json: Print the TOC in JSON format', '', + ' --check: Check whether the TOC is up to date. Print the result to stdout and', + ' exit with status 1 if the TOC is outdated.', + '', ' --append: Append a string to the end of the TOC', '', ' --bullets: Bullets to use for items in the generated TOC', @@ -54,6 +57,11 @@ if (args.i && args._[0] === '-') { process.exit(1); } +if (args.check && (args.i || args.json)) { + console.error('markdown-toc: you cannot use --check with either -i or --json'); + process.exit(1); +} + var input = process.stdin; if (args._[0] !== '-') input = fs.createReadStream(args._[0]); @@ -61,6 +69,15 @@ input.pipe(utils.concat(function(input) { if (args.i) { var newMarkdown = toc.insert(input.toString(), args); fs.writeFileSync(args._[0], newMarkdown); + } else if (args.check) { + var original = input.toString() + var newMarkdown = toc.insert(original, args); + if (newMarkdown === original) { + console.log('TOC is up to date') + } else { + console.log('TOC is out of date') + process.exit(1) + } } else { var parsed = toc(input.toString(), args); output(parsed);