From efe1ee5df979deed375521425196cce33b4ad2ae Mon Sep 17 00:00:00 2001 From: Shane Hughes Date: Wed, 21 Mar 2018 09:21:41 -0500 Subject: [PATCH 1/3] update README --- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b8766c4..b512dec 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ ## Table of Contents -- [Install](#install) -- [CLI](#cli) - [Highlights](#highlights) - [Usage](#usage) - [API](#api) @@ -33,6 +31,20 @@ Install with [npm](https://www.npmjs.com/): $ npm install --save markdown-toc ``` +Install with [yarn](https://yarnpkg.com): + +```sh +$ yarn add 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,7 +53,24 @@ 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 @@ -59,6 +88,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 @@ -304,7 +336,10 @@ Pull requests and stars are always welcome. For bugs and feature requests, [plea | **Commits** | **Contributor** | | --- | --- | | 196 | [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) | @@ -319,9 +354,12 @@ Pull requests and stars are always welcome. For bugs and feature requests, [plea | 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 @@ -351,9 +389,9 @@ $ npm install && npm test ### License -Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). +Copyright © 2018, [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.6.0, on March 21, 2018._ \ No newline at end of file From 4bd20d9501fc5b770ec40482bbb85da082cebfb3 Mon Sep 17 00:00:00 2001 From: Shane Hughes Date: Wed, 21 Mar 2018 11:27:31 -0500 Subject: [PATCH 2/3] escape example toc tag --- .verb.md | 18 +++++++++--------- README.md | 20 ++------------------ 2 files changed, 11 insertions(+), 27 deletions(-) diff --git a/.verb.md b/.verb.md index bdd7611..236a1bc 100644 --- a/.verb.md +++ b/.verb.md @@ -1,4 +1,4 @@ -## Quick Start +## 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:
`` @@ -12,7 +12,7 @@ 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 ; (Without this flag, the default is to print the TOC to stdout.) --json: Print the TOC in JSON format @@ -66,7 +66,7 @@ toc('# One\n\n# Two').content; To allow customization of the output, an object is returned with the following properties: - `content` **{String}**: The generated table of contents. Unless you want to customize rendering, this is all you need. - - `highest` **{Number}**: The highest level heading found. This is used to adjust indentation. + - `highest` **{Number}**: The highest level heading found. This is used to adjust indentation. - `tokens` **{Array}**: Headings tokens that can be used for custom rendering ## API @@ -102,7 +102,7 @@ Results in: ### toc.json -Object for creating a custom TOC. +Object for creating a custom TOC. ```js toc('# AAA\n## BBB\n### CCC\nfoo').json; @@ -116,7 +116,7 @@ toc('# AAA\n## BBB\n### CCC\nfoo').json; ### toc.insert -Insert a table of contents immediately after an _opening_ `` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (``) are found. +Insert a table of contents immediately after an _opening_ `` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (``) are found. _(This strategy works well since code comments in markdown are hidden when viewed as HTML, like when viewing a README on GitHub README for example)._ @@ -160,8 +160,8 @@ var toc = require('markdown-toc'); ``` - `toc.bullets()`: render a bullet list from an array of tokens - `toc.linkify()`: linking a heading `content` string -- `toc.slugify()`: slugify a heading `content` string -- `toc.strip()`: strip words or characters from a heading `content` string +- `toc.slugify()`: slugify a heading `content` string +- `toc.strip()`: strip words or characters from a heading `content` string **Example** @@ -191,7 +191,7 @@ Type: `Function` Default: `undefined` -Params: +Params: - `str` **{String}** the actual heading string - `ele` **{Objecct}** object of heading tokens @@ -199,7 +199,7 @@ Params: **Example** -From time to time, we might get junk like this in our TOC. +From time to time, we might get junk like this in our TOC. ``` [.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading) diff --git a/README.md b/README.md index b512dec..e197978 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ ## Table of Contents +- [CLI](#cli) - [Highlights](#highlights) - [Usage](#usage) - [API](#api) @@ -53,24 +54,7 @@ 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 - [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))_; + -i: Edit the file directly, injecting the TOC at ; (Without this flag, the default is to print the TOC to stdout.) --json: Print the TOC in JSON format From 64af9117f5dbd7bedf3a974d118f7f112546cbe6 Mon Sep 17 00:00:00 2001 From: Shane Hughes Date: Wed, 21 Mar 2018 11:30:09 -0500 Subject: [PATCH 3/3] escape initial toc tag example to include all headings in actual toc --- .verb.md | 2 +- README.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.verb.md b/.verb.md index 236a1bc..beaa470 100644 --- a/.verb.md +++ b/.verb.md @@ -1,7 +1,7 @@ ## 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:
`` +2. Edit README.md and insert the following line where you want the TOC inserted:
`` 3. `$ markdown-toc -i README.md` ## CLI diff --git a/README.md b/README.md index e197978..ebfcace 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ ## Table of Contents +- [Install](#install) +- [Quick Start](#quick-start) - [CLI](#cli) - [Highlights](#highlights) - [Usage](#usage)