@substrate-system/markdown-toc 1.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2023, Jon Schlinkert.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,419 @@
+# markdown-toc
+
+Generate a markdown TOC (table of contents) with Remarkable.
+
+Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
+
+## fork
+
+This is a fork of [jonschlinkert/markdown-toc](https://github.com/jonschlinkert/markdown-toc).
+
+<details>
+<summary><h2>Contents</h2></summary>
+
+- [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)
+
+</details>
+
+## Install
+
+Install with [npm](https://www.npmjs.com/):
+
+```sh
+npm i -D @substrate-system/markdown-toc
+```
+
+# Sponsors
+
+Thanks to the following companies, organizations, and individuals for supporting the ongoing maintenance and development of markdown-toc! [Become a Sponsor](https://github.com/sponsors/jonschlinkert) to add your logo to this README, or any of [my other projects](https://github.com/jonschlinkert?tab=repositories&q=&type=&language=&sort=stargazers)
+
+## Gold Sponsors
+
+| [<img src="https://github.com/jonschlinkert/clone-deep/assets/383994/98036489-2cae-48a2-8d29-7dec58ea05c4" alt="https://jaake.tech/" width="100"/>](https://jaake.tech/) |
+|:---:|
+| [https://jaake.tech/](https://jaake.tech/) |
+
+<br />
+
+## 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:<br />`<!-- toc -->`
+3. `$ markdown-toc -i README.md`
+
+## CLI
+
+```
+Usage: markdown-toc [options] <input>
+
+  input:        The Markdown file to parse for table of contents,
+                or "-" to read from stdin.
+
+  -i:           Edit the <input> 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
+
+  --append:     Append a string to the end of the TOC
+
+  --bullets:    Bullets to use for items in the generated TOC
+                (Supports multiple bullets: --bullets "*" --bullets "-" --bullets "+")
+                (Default is "*".)
+
+  --maxdepth:   Use headings whose depth is at most maxdepth
+                (Default is 6.)
+
+  --no-firsth1: Include the first h1-level heading in a file
+
+  --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
+
+**Features**
+
+* Can optionally be used as a [remarkable](https://github.com/jonschlinkert/remarkable) plugin
+* Returns an object with the rendered TOC (on `content`), as well as a `json` property with the raw TOC object, so you can generate your own TOC using templates or however you want
+* Works with [repeated headings](https://gist.github.com/jonschlinkert/ac5d8122bfaaa394f896)
+* Uses sane defaults, so no customization is necessary, but you can if you need to.
+* [filter](#filter-headings) out headings you don't want
+* [Improve](#titleize) the headings you do want
+* Use a custom [slugify](#optionsslugify) function to change how links are created
+
+**Safe!**
+
+* Won't mangle markdown in code examples in gfm code blocks that other TOC generators mistake as being actual headings (this happens when markdown headings are show in _examples_, meaning they arent' actually headings that should be in the toc. Also happens with yaml and coffee-script comments, or any comments that use `#`)
+* Won't mangle front-matter, or mistake front-matter properties for headings like other TOC generators
+
+## Usage
+
+```js
+var toc = require('markdown-toc');
+
+toc('# One\n\n# Two').content;
+// Results in:
+// - [One](#one)
+// - [Two](#two)
+```
+
+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.
+* `tokens` **{Array}**: Headings tokens that can be used for custom rendering
+
+## API
+
+### toc.plugin
+
+Use as a [remarkable](https://github.com/jonschlinkert/remarkable) plugin.
+
+```js
+var Remarkable = require('remarkable');
+var toc = require('markdown-toc');
+
+function render(str, options) {
+  return new Remarkable()
+    .use(toc.plugin(options)) // <= register the plugin
+    .render(str);
+}
+```
+
+**Usage example**
+
+```js
+var results = render('# AAA\n# BBB\n# CCC\nfoo\nbar\nbaz');
+```
+
+Results in:
+
+```
+- [AAA](#aaa)
+- [BBB](#bbb)
+- [CCC](#ccc)
+```
+
+### toc.json
+
+Object for creating a custom TOC.
+
+```js
+toc('# AAA\n## BBB\n### CCC\nfoo').json;
+
+// results in
+[ { content: 'AAA', slug: 'aaa', lvl: 1 },
+  { content: 'BBB', slug: 'bbb', lvl: 2 },
+  { content: 'CCC', slug: 'ccc', lvl: 3 } ]
+```
+
+### toc.insert
+
+Insert a table of contents immediately after an _opening_ `<!-- toc -->` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`<!-- tocstop -->`) 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)._
+
+**Example**
+
+```
+<!-- toc -->
+- old toc 1
+- old toc 2
+- old toc 3
+<!-- tocstop -->
+
+## abc
+This is a b c.
+
+## xyz
+This is x y z.
+```
+
+Would result in something like:
+
+```
+<!-- toc -->
+- [abc](#abc)
+- [xyz](#xyz)
+<!-- tocstop -->
+
+## abc
+This is a b c.
+
+## xyz
+This is x y z.
+```
+
+### Utility functions
+
+As a convenience to folks who wants to create a custom TOC, markdown-toc's internal utility methods are exposed:
+
+```js
+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
+
+**Example**
+
+```js
+var result = toc('# AAA\n## BBB\n### CCC\nfoo');
+var str = '';
+
+result.json.forEach(function(heading) {
+  str += toc.linkify(heading.content);
+});
+```
+
+## Options
+
+### options.append
+
+Append a string to the end of the TOC.
+
+```js
+toc(str, {append: '\n_(TOC generated by Verb)_'});
+```
+
+### options.filter
+
+Type: `Function`
+
+Default: `undefined`
+
+Params:
+
+* `str` **{String}** the actual heading string
+* `ele` **{Objecct}** object of heading tokens
+* `arr` **{Array}** all of the headings objects
+
+**Example**
+
+From time to time, we might get junk like this in our TOC.
+
+```
+[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
+```
+
+Unless you like that kind of thing, you might want to filter these bad headings out.
+
+```js
+function removeJunk(str, ele, arr) {
+  return str.indexOf('...') === -1;
+}
+
+var result = toc(str, {filter: removeJunk});
+//=> beautiful TOC
+```
+
+### options.slugify
+
+Type: `Function`
+
+Default: Basic non-word character replacement.
+
+**Example**
+
+```js
+var str = toc('# Some Article', {slugify: require('uslug')});
+```
+
+### options.bullets
+
+Type: `String|Array`
+
+Default: `*`
+
+The bullet to use for each item in the generated TOC. If passed as an array (`['*', '-', '+']`), the bullet point strings will be used based on the header depth.
+
+### options.maxdepth
+
+Type: `Number`
+
+Default: `6`
+
+Use headings whose depth is at most maxdepth.
+
+### options.firsth1
+
+Type: `Boolean`
+
+Default: `true`
+
+Exclude the first h1-level heading in a file. For example, this prevents the first heading in a README from showing up in the TOC.
+
+### options.stripHeadingTags
+
+Type: `Boolean`
+
+Default: `true`
+
+Strip extraneous HTML tags from heading text before slugifying. This is similar to GitHub markdown behavior.
+
+## About
+
+<details>
+<summary><strong>Contributing</strong></summary>
+
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
+
+</details>
+
+<details>
+<summary><strong>Running Tests</strong></summary>
+
+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
+```
+
+</details>
+
+<details>
+<summary><strong>Building docs</strong></summary>
+
+_(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
+```
+
+</details>
+
+### 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): 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.")
+
+### Contributors
+
+| **Commits** | **Contributor** |
+| --- | --- |
+| 199 | [jonschlinkert](https://github.com/jonschlinkert) |
+| 9   | [doowb](https://github.com/doowb) |
+| 4   | [dbooth-boston](https://github.com/dbooth-boston) |
+| 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   | [zeke](https://github.com/zeke) |
+| 1   | [Vortex375](https://github.com/Vortex375) |
+| 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) |
+
+### Author
+
+**Jon Schlinkert**
+
+* [GitHub Profile](https://github.com/jonschlinkert)
+* [Twitter Profile](https://twitter.com/jonschlinkert)
+* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
+
+### License
+
+Copyright © 2023, [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.8.0, on July 12, 2023._

package/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+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'],
+  string: ['append', 'bullets', 'indent'],
+  default: {
+    firsth1: true,
+    stripHeadingTags: true
+  }
+});
+
+if (args._.length !== 1) {
+  console.error([
+    'Usage: markdown-toc [options] <input> ',
+    '',
+    '  input:        The Markdown file to parse for table of contents,',
+    '                or "-" to read from stdin.',
+    '',
+    '  -i:           Edit the <input> file directly, injecting the TOC at <!-- toc -->',
+    '                (Without this flag, the default is to print the TOC to stdout.)',
+    '',
+    '  --json:       Print the TOC in JSON format',
+    '',
+    '  --append:     Append a string to the end of the TOC',
+    '',
+    '  --bullets:    Bullets to use for items in the generated TOC',
+    '                (Supports multiple bullets: --bullets "*" --bullets "-" --bullets "+")',
+    '                (Default is "*".)',
+    '',
+    '  --maxdepth:   Use headings whose depth is at most maxdepth',
+    '                (Default is 6.)',
+    '',
+    '  --no-firsth1: Include the first h1-level heading in a file',
+    '',
+    '  --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\')'
+  ].join('\n'));
+  process.exit(1);
+}
+
+if (args.i && args.json) {
+  console.error('markdown-toc: you cannot use both --json and -i');
+  process.exit(1);
+}
+
+if (args.i && args._[0] === '-') {
+  console.error('markdown-toc: you cannot use -i with "-" (stdin) for input');
+  process.exit(1);
+}
+
+var input = process.stdin;
+if (args._[0] !== '-') input = fs.createReadStream(args._[0]);
+
+input.pipe(utils.concat(function(input) {
+  if (args.i) {
+    var newMarkdown = toc.insert(input.toString(), args);
+    fs.writeFileSync(args._[0], newMarkdown);
+  } else {
+    var parsed = toc(input.toString(), args);
+    output(parsed);
+  }
+}));
+
+input.on('error', function onErr(err) {
+  console.error(err);
+  process.exit(1);
+});
+
+function output(parsed) {
+  if (args.json) return console.log(JSON.stringify(parsed.json, null, '  '));
+  process.stdout.write(parsed.content);
+}

package/index.js

@@ -0,0 +1,255 @@
+'use strict';
+
+/*!
+ * markdown-toc <https://github.com/jonschlinkert/markdown-toc>
+ *
+ * Copyright © 2013-2023, Jon Schlinkert.
+ * Released under the MIT License.
+ */
+
+var utils = require('./lib/utils');
+var querystring = require('querystring');
+
+/**
+ * expose `toc`
+ */
+
+module.exports = toc;
+
+/**
+ * Load `generate` as a remarkable plugin and
+ * expose the `toc` function.
+ *
+ * @param  {String} `str` String of markdown
+ * @param  {Object} `options`
+ * @return {String} Markdown-formatted table of contents
+ */
+
+function toc(str, options) {
+  return new utils.Remarkable()
+    .use(generate(options))
+    .render(str);
+}
+
+/**
+ * Expose `insert` method
+ */
+
+toc.insert = require('./lib/insert');
+
+/**
+ * Generate a markdown table of contents. This is the
+ * function that does all of the main work with Remarkable.
+ *
+ * @param {Object} `options`
+ * @return {String}
+ */
+
+function generate(options) {
+  var opts = utils.merge({firsth1: true, maxdepth: 6}, options);
+  var stripFirst = opts.firsth1 === false;
+  if (typeof opts.linkify === 'undefined') opts.linkify = true;
+
+  return function(md) {
+    md.renderer.render = function(tokens) {
+      tokens = tokens.slice();
+      var seen = {};
+      var len = tokens.length, i = 0, num = 0;
+      var tocstart = -1;
+      var arr = [];
+      var res = {};
+
+      while (len--) {
+        var token = tokens[i++];
+        if (/<!--[ \t]*toc[ \t]*-->/.test(token.content)) {
+          tocstart = token.lines[1];
+        }
+
+        if (token.type === 'heading_open') {
+          tokens[i].lvl = tokens[i - 1].hLevel;
+          tokens[i].i = num++;
+          arr.push(tokens[i]);
+        }
+      }
+
+      var result = [];
+      res.json = [];
+
+      // exclude headings that come before the actual
+      // table of contents.
+      var alen = arr.length, j = 0;
+      while (alen--) {
+        var tok = arr[j++];
+
+        if (tok.lines && (tok.lines[0] > tocstart)) {
+          var val = tok.content;
+          if (tok.children && tok.children[0].type === 'link_open') {
+            if (tok.children[1].type === 'text') {
+              val = tok.children[1].content;
+            }
+          }
+
+          if (!seen.hasOwnProperty(val)) {
+            seen[val] = 0;
+          } else {
+            seen[val]++;
+          }
+
+          tok.seen = opts.num = seen[val];
+          tok.slug = utils.slugify(val, opts);
+          res.json.push(utils.pick(tok, ['content', 'slug', 'lvl', 'i', 'seen']));
+          if (opts.linkify) tok = linkify(tok, opts);
+          result.push(tok);
+        }
+      }
+
+      opts.highest = highest(result);
+      res.highest = opts.highest;
+      res.tokens = tokens;
+
+      if (stripFirst) result = result.slice(1);
+      res.content = bullets(result, opts);
+      res.content += (opts.append || '');
+      return res;
+    };
+  };
+}
+
+/**
+ * Render markdown list bullets
+ *
+ * @param  {Array} `arr` Array of listitem objects
+ * @param  {Object} `opts`
+ * @return {String}
+ */
+
+function bullets(arr, options) {
+  var opts = utils.merge({indent: '  '}, options);
+  opts.chars = opts.chars || opts.bullets || ['-', '*', '+'];
+  var unindent = 0;
+
+  var listitem = utils.li(opts);
+  var fn = typeof opts.filter === 'function'
+    ? opts.filter
+    : null;
+
+  // Keep the first h1? This is `true` by default
+  if (opts && opts.firsth1 === false) {
+    unindent = 1;
+  }
+
+  var len = arr.length;
+  var res = [];
+  var i = 0;
+
+  while (i < len) {
+    var ele = arr[i++];
+    ele.lvl -= unindent;
+    if (fn && !fn(ele.content, ele, arr)) {
+      continue;
+    }
+
+    if (ele.lvl > opts.maxdepth) {
+      continue;
+    }
+
+    var lvl = ele.lvl - opts.highest;
+    res.push(listitem(lvl, ele.content, opts));
+  }
+  return res.join('\n');
+}
+
+/**
+ * Get the highest heading level in the array, so
+ * we can un-indent the proper number of levels.
+ *
+ * @param {Array} `arr` Array of tokens
+ * @return {Number} Highest level
+ */
+
+function highest(arr) {
+  var res = arr.slice().sort(function(a, b) {
+    return a.lvl - b.lvl;
+  });
+  if (res && res.length) {
+    return res[0].lvl;
+  }
+  return 0;
+}
+
+/**
+ * Turn headings into anchors
+ */
+
+function linkify(tok, options) {
+  var opts = utils.merge({}, options);
+  if (tok && tok.content) {
+    opts.num = tok.seen;
+    var text = titleize(tok.content, opts);
+    var slug = utils.slugify(tok.content, opts);
+    slug = querystring.escape(slug);
+    if (opts && typeof opts.linkify === 'function') {
+      return opts.linkify(tok, text, slug, opts);
+    }
+    tok.content = utils.mdlink(text, '#' + slug);
+  }
+  return tok;
+}
+
+/**
+ * Titleize the title part of a markdown link.
+ *
+ * @name  options.titleize
+ * @param  {String} `str` The string to titleize
+ * @param  {Object} `opts` Pass a custom titleize function on `titleize`
+ * @return {String}
+ * @api public
+ */
+
+function titleize(str, opts) {
+  if (opts && opts.strip) { return strip(str, opts); }
+  if (opts && opts.titleize === false) return str;
+  if (opts && typeof opts.titleize === 'function') {
+    return opts.titleize(str, opts);
+  }
+  str = utils.getTitle(str);
+  str = str.split(/<\/?[^>]+>/).join('');
+  str = str.split(/[ \t]+/).join(' ');
+  return str.trim();
+}
+
+/**
+ * Optionally strip specified words from heading text (not url)
+ *
+ * @name  options.strip
+ * @param  {String} `str`
+ * @param  {String} `opts`
+ * @return {String}
+ */
+
+function strip(str, opts) {
+  opts = opts || {};
+  if (!opts.strip) return str;
+  if (typeof opts.strip === 'function') {
+    return opts.strip(str, opts);
+  }
+  if (Array.isArray(opts.strip) && opts.strip.length) {
+    var res = opts.strip.join('|');
+    var re = new RegExp(res, 'g');
+    str = str.trim().replace(re, '');
+    return str.replace(/^-|-$/g, '');
+  }
+  return str;
+}
+
+/**
+ * Expose utils
+ */
+
+toc.utils = utils;
+toc.bullets = bullets;
+toc.linkify = linkify;
+toc.slugify = utils.slugify;
+toc.titleize = titleize;
+toc.plugin = generate;
+toc.strip = strip;

package/lib/insert.js

@@ -0,0 +1,67 @@
+'use strict';
+
+var toc = require('..');
+var utils = require('./utils');
+
+/**
+ * The basic idea:
+ *
+ *  1. when front-matter exists, we need to avoid turning its properties into headings.
+ *  2. We need to detect toc markers on the page. For now it's a simple HTML code comment
+ *     to ensure the markdown is compatible with any parser.
+ *
+ * @param  {String} `str` Pass a string of markdown
+ * @param  {Object} `options` Pass options to toc generation
+ * @return {String} Get the same string back with a TOC inserted
+ */
+
+module.exports = function insert(str, options) {
+  options = options || {};
+
+  var regex = options.regex || /(?:<!-- toc(?:\s*stop)? -->)/g;
+  var open = typeof options.open === 'string' ? options.open : '<!-- toc -->\n\n';
+  var close = typeof options.close === 'string' ? options.close : '<!-- tocstop -->';
+  var obj;
+
+  var newlines = '';
+  var m = /\n+$/.exec(str);
+  if (m) newlines = m[0];
+
+  // does the file have front-matter?
+  if (/^---/.test(str)) {
+    // extract it temporarily so the syntax
+    // doesn't get mistaken for a heading
+    obj = utils.matter(str);
+    str = obj.content;
+  }
+
+  var sections = split(str, regex);
+  if (sections.length > 3) {
+    throw new Error('markdown-toc only supports one Table of Contents per file.');
+  }
+
+  var last = sections[sections.length - 1];
+  if (sections.length === 3) {
+    sections.splice(1, 1, open + (options.toc || toc(last, options).content));
+    sections.splice(2, 0, close);
+  }
+
+  if (sections.length === 2) {
+    sections.splice(1, 0, open + toc(last, options).content + '\n\n' + close);
+  }
+
+  var resultString = sections.join('\n\n') + newlines;
+  // if front-matter was found, put it back now
+  if (obj) {
+    return utils.matter.stringify(resultString, obj.data);
+  }
+  return resultString;
+};
+
+function split(str, re) {
+  return str.split(re).map(trim);
+}
+
+function trim(str) {
+  return str.trim();
+}

package/lib/utils.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Module dependencies
+ */
+
+var diacritics = require('diacritics-map');
+var utils = require('lazy-cache')(require);
+var fn = require;
+require = utils;
+
+/**
+ * Lazily required module dependencies
+ */
+
+require('concat-stream', 'concat');
+require('gray-matter', 'matter');
+require('list-item', 'li');
+require('markdown-link', 'mdlink');
+require('minimist');
+require('mixin-deep', 'merge');
+require('object.pick', 'pick');
+require('remarkable', 'Remarkable');
+require('repeat-string', 'repeat');
+require('strip-color');
+require = fn;
+
+/**
+ * Get the "title" from a markdown link
+ */
+
+utils.getTitle = function(str) {
+  if (/^\[[^\]]+\]\(/.test(str)) {
+    var m = /^\[([^\]]+)\]/.exec(str);
+    if (m) return m[1];
+  }
+  return str;
+};
+
+/**
+ * Slugify the url part of a markdown link.
+ *
+ * @name  options.slugify
+ * @param  {String} `str` The string to slugify
+ * @param  {Object} `options` Pass a custom slugify function on `options.slugify`
+ * @return {String}
+ * @api public
+ */
+
+utils.slugify = function(str, options) {
+  options = options || {};
+  if (options.slugify === false) return str;
+  if (typeof options.slugify === 'function') {
+    return options.slugify(str, options);
+  }
+
+  str = utils.getTitle(str);
+  str = utils.stripColor(str);
+  str = str.toLowerCase();
+
+  // `.split()` is often (but not always) faster than `.replace()`
+  str = str.split(' ').join('-');
+  str = str.split(/\t/).join('--');
+  if (options.stripHeadingTags !== false) {
+    str = str.split(/<\/?[^>]+>/).join('');
+  }
+  str = str.split(/[|$&`~=\\\/@+*!?({[\]})<>=.,;:'"^]/).join('');
+  str = str.split(/[。？！，、；：“”【】（）〔〕［］﹃﹄“ ”‘’﹁﹂—…－～《》〈〉「」]/).join('');
+  str = replaceDiacritics(str);
+  if (options.num) {
+    str += '-' + options.num;
+  }
+  return str;
+};
+
+function replaceDiacritics(str) {
+  return str.replace(/[À-ž]/g, function(ch) {
+    return diacritics[ch] || ch;
+  });
+}
+
+/**
+ * Expose `utils` modules
+ */
+
+module.exports = utils;

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@substrate-system/markdown-toc",
+  "description": "Generate a markdown TOC (table of contents) with Remarkable.",
+  "version": "1.3.3",
+  "homepage": "https://github.com/jonschlinkert/markdown-toc",
+  "author": "Jon Schlinkert (https://github.com/jonschlinkert)",
+  "scripts": {
+    "version": "npm run changelog && git add CHANGELOG.md",
+    "changelog": "auto-changelog -p --template keepachangelog --breaking-pattern 'BREAKING CHANGE:'",
+    "postversion": "git push --follow-tags && npm publish --access=public",
+    "test": "mocha"
+  },
+  "dependencies": {
+    "concat-stream": "^1.5.2",
+    "diacritics-map": "^0.1.0",
+    "gray-matter": "^4.0.3",
+    "lazy-cache": "^2.0.2",
+    "list-item": "^1.1.1",
+    "markdown-link": "^0.1.1",
+    "minimist": "^1.2.0",
+    "mixin-deep": "^1.1.3",
+    "object.pick": "^1.3.0",
+    "remarkable": "^1.7.1",
+    "repeat-string": "^1.6.1",
+    "strip-color": "^0.1.0"
+  },
+  "devDependencies": {
+    "auto-changelog": "^2.5.0",
+    "mocha": "^10.2.0"
+  },
+  "contributors": [
+    "=^._.^= (http://maxogden.com)",
+    "Andrés (http://angrykoala.github.io)",
+    "Benjamin Schmitz (https://github.com/Vortex375)",
+    "Christian Raunitschka (raunitschka.de)",
+    "Daniel Chen (http://chendaniely.github.io)",
+    "Daniel Mietchen (http://about.me/daniel.mietchen)",
+    "David Mohl (https://dvcrn.github.io)",
+    "Federico Soave (https://github.com/Feder1co5oave)",
+    "Gary Green (https://github.com/garygreen)",
+    "Jon Schlinkert (http://twitter.com/jonschlinkert)",
+    "Josh Duff (https://tehshrike.github.io)",
+    "Matt Ellis (http://sticklebackplastic.com)",
+    "Nicolas Morel (https://github.com/Marsup)",
+    "Rafael Steil (http://rafaelsteil.com)",
+    "Richard Bradley (https://github.com/RichardBradley)",
+    "Seth Vincent (https://sethvincent.com)",
+    "Stefan Walther (http://qliksite.io)",
+    "Tao Wang (https://github.com/twang2218)",
+    "(https://github.com/lu22do)",
+    "Zeke Sikelianos (http://zeke.sikelianos.com)"
+  ],
+  "repository": "bicycle-codes/markdown-toc",
+  "bugs": {
+    "url": "https://github.com/bicycle-codes/markdown-toc/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "cli.js",
+    "index.js",
+    "lib"
+  ],
+  "main": "index.js",
+  "bin": {
+    "markdown-toc": "cli.js"
+  },
+  "engines": {
+    "node": ">=0.10.0"
+  },
+  "keywords": [
+    "anchor",
+    "API documentation",
+    "code documentation",
+    "commonmark",
+    "content navigation",
+    "content organization",
+    "developer tools",
+    "docs",
+    "document structure",
+    "document",
+    "documentation tool",
+    "documentation",
+    "glossary",
+    "heading",
+    "headings",
+    "index",
+    "javascript",
+    "links",
+    "markdown parser",
+    "markdown tools",
+    "Markdown-based",
+    "markdown-toc",
+    "markdown",
+    "markup language",
+    "md files",
+    "md parser",
+    "md-toc",
+    "md",
+    "node.js",
+    "npm",
+    "open-source",
+    "outline",
+    "package.json",
+    "plugin",
+    "README tool",
+    "readme",
+    "reference",
+    "remarkable",
+    "remarkableplugin",
+    "render",
+    "renderer",
+    "structure",
+    "table of contents",
+    "table-of-contents",
+    "table",
+    "toc-generator",
+    "toc",
+    "write"
+  ]
+}