@uniquedivine/ud-mdtoc 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2014-present, Jon Schlinkert.
+Copyright (c) 2023-present, Unique Divine.
+
+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

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# ud-mdtoc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate a Markdown table of contents from headings, or update one between
+`<!-- toc -->` and `<!-- tocstop -->` markers. Package
+`@uniquedivine/ud-mdtoc` installs command `ud-mdtoc` and supports the `ud`
+executable plugin interface.
+
+Requires Bun 1.2 or later on Linux, macOS, or WSL. The executable uses
+`env -S bun --no-install`, so missing dependencies fail instead of loading
+packages from Bun's runtime auto-install cache.
+
+## Install
+
+```sh
+bun add --global @uniquedivine/ud-mdtoc@0.1.0
+ud-mdtoc --version
+ud-mdtoc --help
+```
+
+The package ships TypeScript source and declares its runtime dependencies.
+Installing from npm installs those dependencies independently of a Jiyuu checkout.
+The separate upstream command `markdown-toc` can remain installed alongside it.
+
+## Generate a Table of Contents
+
+```sh
+ud-mdtoc notes.md
+ud-mdtoc 'notes with spaces.md' --bullets=- --maxdepth=3 --no-firsth1
+printf '# Title\n\n## First\n\n### Second\n' |
+  ud-mdtoc - --bullets=- --maxdepth=3 --no-firsth1
+```
+
+The last command prints:
+
+```markdown
+- [First](#first)
+  - [Second](#second)
+```
+
+Without `--bullets`, the list markers rotate through `-`, `*`, and `+` by
+depth. `--maxdepth` limits the absolute heading level. `--no-firsth1` omits
+the initial level-one title. Headings inside fenced code blocks are ignored.
+
+## Update a File
+
+Place an opening marker before the headings to list:
+
+```markdown
+# Notes
+
+<!-- toc -->
+
+## First
+
+### Second
+```
+
+Then run:
+
+```sh
+ud-mdtoc notes.md -i --bullets=- --maxdepth=3 --no-firsth1
+```
+
+The command inserts the TOC and a closing `<!-- tocstop -->` marker. Later runs
+replace the content between the markers. Only one TOC is supported per file.
+The command writes the input file directly, so save editor changes first.
+
+For Neovim, commands `:Toc` and `:TocCopy` are configured in the owner's dotfiles.
+They use the installed command with these same bullet and heading flags.
+
+## Options
+
+| Option                        | Behavior                                         |
+| ----------------------------- | ------------------------------------------------ |
+| `-i`                          | Update the input file at its TOC marker          |
+| `--json`                      | Print parsed heading metadata as JSON            |
+| `--bullets=-`                 | Use one marker at every depth                    |
+| `--bullets '*' --bullets '-'` | Rotate the specified markers by depth            |
+| `--maxdepth=3`                | Render heading levels one through three          |
+| `--no-firsth1`                | Omit the first level-one heading                 |
+| `--no-stripHeadingTags`       | Preserve HTML tags when generating heading slugs |
+| `--indent='    '`             | Use four spaces per nesting level                |
+| `--append=TEXT`               | Append text to the rendered TOC                  |
+| `-h`, `--help`                | Show usage                                       |
+| `-v`, `--version`             | Show the installed version                       |
+| `--plugin-info`               | Print the `ud` plugin metadata as JSON           |
+
+Use `-` as the input filename to read stdin. In-place mode requires a file and
+cannot be combined with `--json`. JSON exposes parsed heading metadata; the
+rendered TOC's depth limit does not filter that metadata.
+
+## Use as a ud Plugin
+
+The `ud` dispatcher discovers executable plugins in its XDG plugin directory,
+not on the general `PATH`. Register the installed command:
+
+```sh
+plugin_dir="${XDG_DATA_HOME:-$HOME/.local/share}/ud/plugins"
+mkdir -p "$plugin_dir"
+ln -sfn "$(bun pm bin --global)/ud-mdtoc" "$plugin_dir/ud-mdtoc"
+ud plugin info mdtoc
+ud mdtoc --help
+ud mdtoc notes.md --bullets=- --maxdepth=3 --no-firsth1
+```
+
+The owner's dotfiles restore this link through `just sync` and inspect it through
+`just health`.
+
+## Develop and Validate
+
+From this directory:
+
+```sh
+just install
+just test
+just typecheck
+just lint
+just smoke-test
+just validate
+```
+
+`just smoke-test` packs the publication files, installs the tarball into a
+disposable Bun global directory, and runs the installed command outside the
+checkout. It checks metadata, stdin, filenames containing spaces, repeated
+in-place updates, and failure after deleting a runtime dependency. It does not
+replace the workstation's installed package.
+
+`just validate` runs the tests, type checking, package lint, tarball smoke test,
+and npm publication dry run. Type checking uses native `bun check`.
+
+## Publish
+
+Publishing follows the `tg-sai` workflow with pinned `npm@12.2.0`. Commands use
+Bun, Just, `jq`, and `rg`. Run the checks before the publication command:
+
+```sh
+just validate
+bunx npm@12.2.0 login --auth-type=web
+just publish
+```
+
+`just publish` verifies npm login, rejects a version that is already published,
+and repeats the npm publication dry run. It then prints the browser
+confirmation URL for the owner to complete 2FA. Publishing is explicit and is
+never part of `just sync`.
+
+For later releases, edit the version in `package.json`, run `just validate`,
+commit the release changes, and run `just publish`. After publication, update
+the exact version in the owner's dotfiles Bun manifest and refresh its lockfile.
+
+## Attribution
+
+This project is a TypeScript fork of
+[Jon Schlinkert's markdown-toc](https://github.com/jonschlinkert/markdown-toc).
+It retains the original contributors in `package.json` and the MIT license in
+[LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@uniquedivine/ud-mdtoc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Generate Markdown tables of contents with Bun or the ud command router.",
+  "version": "0.1.0",
+  "homepage": "https://github.com/Unique-Divine/jiyuu/tree/main/mdtoc",
+  "author": "Unique Divine (https://github.com/Unique-Divine)",
+  "contributors": [
+    "Jon Schlinkert (http://twitter.com/jonschlinkert)",
+    "=^._.^= (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)",
+    "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": {
+    "type": "git",
+    "url": "git+https://github.com/Unique-Divine/jiyuu.git",
+    "directory": "mdtoc"
+  },
+  "bugs": {
+    "url": "https://github.com/Unique-Divine/jiyuu/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "src/mdtoc/index.ts",
+  "bin": {
+    "ud-mdtoc": "src/cli.ts"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun check"
+  },
+  "dependencies": {
+    "concat-stream": "^1.5.2",
+    "diacritics-map": "^0.1.0",
+    "gray-matter": "^3.1.1",
+    "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.2.0",
+    "remarkable": "^2.0.1",
+    "repeat-string": "^1.6.1",
+    "strip-color": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3",
+    "@types/concat-stream": "^2.0.3",
+    "@types/minimist": "^1.2.5",
+    "@types/remarkable": "^2.0.8",
+    "@types/strip-color": "^0.1.2",
+    "globals": "^15.4.0",
+    "gulp-format-md": "^2.0.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.2.2"
+  },
+  "keywords": [
+    "markdown",
+    "table-of-contents",
+    "toc",
+    "bun",
+    "ud-plugin"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env -S bun --no-install
+
+import * as fs from "fs"
+import { Readable } from "stream"
+import { toc, minimist, concat, Toc } from "./mdtoc"
+import { type TocResult } from "./mdtoc/toc"
+import { version } from "../package.json"
+// const utils = require("./lib/utils")
+
+/**
+ * Parse command-line arguments (`process.argv`) from index 2 into `args` using the
+ * `minimist` package. Depending on the command-line args, the script outputs
+ * the generated table of contents or JSON representation to stdout. If the -i
+ * flag is specified, the modified Markdown content is written back to the input
+ * file inplace. */
+const args = minimist(process.argv.slice(2), {
+  // boolean flags: "-i", "--json", ...
+  boolean: [
+    "i",
+    "json",
+    "firsth1",
+    "stripHeadingTags",
+    "help",
+    "version",
+    "plugin-info",
+  ],
+  alias: { h: "help", v: "version" },
+  // string flags: Flags that take string args
+  string: ["append", "bullets", "indent"],
+  // default values for flags
+  default: {
+    firsth1: true,
+    stripHeadingTags: true,
+  },
+}) as CmdRootArgs
+
+type CmdRootArgs = {
+  help: boolean
+  version: boolean
+  "plugin-info": boolean
+  /** i: Toggles whether to write back to the input file in-place. Cannot be used
+   * with --json. */
+  i: boolean
+  /** json: Toggles whether to print the TOC in JSON format */
+  json: boolean
+  /** firsth1: Toggles whether to include the first `<h1>` element in the TOC.
+   * This first heading is often exlcuded and assumed to be the title of the
+   * Markdown document. */
+  firsth1: boolean
+  stripHeadingTags: boolean
+  append: string
+  /** bullets: Characters to use for bullet points at each depth. */
+  bullets: string | string[]
+  indent: string
+  _: string[]
+}
+
+if (args["plugin-info"]) {
+  console.log(
+    JSON.stringify({
+      apiVersion: 1,
+      name: "mdtoc",
+      description: "Generate Markdown tables of contents",
+    }),
+  )
+  process.exit(0)
+}
+
+if (args.version) {
+  console.log(`ud-mdtoc ${version}`)
+  process.exit(0)
+}
+
+// If the number of positional arguments is not exactly 1, the script exits with
+// a failure status code and prints usage.
+if (args.help || args._.length !== 1) {
+  console.info(
+    [
+      "Usage: ud-mdtoc [options] <input> ",
+      "",
+      "  -h, --help:  Show usage",
+      "  -v, --version: Show the installed version",
+      "  --plugin-info: Print ud plugin metadata as JSON",
+      "",
+      "  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 "-", "*", "+" by depth.)',
+      "",
+      "  --maxdepth:   Use headings whose depth is at most maxdepth",
+      "                (Default is 6.)",
+      "",
+      "  --no-firsth1: Omit the first h1-level heading from the TOC",
+      "",
+      "  --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(args.help ? 0 : 1)
+}
+
+if (args.i && args.json) {
+  console.error("ud-mdtoc: you cannot use both --json and -i")
+  process.exit(1)
+}
+
+if (args.i && args._[0] === "-") {
+  console.error('ud-mdtoc: you cannot use -i with "-" (stdin) for input')
+  process.exit(1)
+}
+
+/**
+ * `process.stdin` is a `tty.ReadStream` and `fs.createReadStream` returns an
+ * `fs.ReadStream`, but both extend `stream.Readable`, so we type the variable
+ * with the shared base class.
+ * */
+let input: Readable = process.stdin
+if (args._[0] !== "-") input = fs.createReadStream(args._[0])
+
+input.pipe(
+  concat((input: Buffer) => {
+    if (args.i) {
+      const newMarkdown = Toc.insert(input.toString(), args)
+      fs.writeFileSync(args._[0], newMarkdown)
+    } else {
+      const parsed = toc(input.toString(), args)
+      writeToStdOut(parsed, args.json)
+    }
+  }),
+)
+
+input.on("error", (err) => {
+  console.error(err)
+  process.exit(1)
+})
+
+function writeToStdOut(parsed: TocResult, useJson: boolean) {
+  if (useJson) return console.log(JSON.stringify(parsed.json, null, "  "))
+  process.stdout.write(parsed.content)
+}

package/src/mdtoc/generate.ts

@@ -0,0 +1,421 @@
+/**
+ * src/mdtoc/generate.ts
+ *
+ * markdown-toc <https://github.com/Unique-Divine/jiyuu/mdtoc>
+ *
+ * Forked from legacy code:
+ * - markdown-toc <https://github.com/jonschlinkert/markdown-toc>
+ *
+ * Released under the MIT License.
+ */
+
+import * as querystring from "querystring" // NOTE querystring API is deprecated
+import markdownLink from "markdown-link"
+import listitem from "list-item"
+import { RemarkablePlus } from "./remarkable"
+import { slugify, type SlugifyOptions, getTitle } from "./options"
+import { insert } from "./insert"
+
+export { insert }
+
+export { slugify }
+
+export interface GenerateOptions extends SlugifyOptions {
+  firsth1?: boolean
+  maxdepth?: number
+  linkify?: boolean | LinkifyFn
+  num?: number
+  strip?: boolean | string[] | StripFn
+  titleize?: boolean | TitleizeFn
+  // Add other possible options here...
+  hLevel?: number
+  bullets?: string | string[]
+  chars?: string | string[]
+
+  /**
+   * filter (`FilterFn`): returns truthy to include the item, falsy to exclude it.
+   * The return value is checked for truthiness, not used as a replacement.
+   * */
+  filter?: FilterFn
+  append?: string
+  highest?: number
+}
+
+type LinkifyFn = (
+  tok: Token,
+  text: string,
+  slug: string,
+  options: GenerateOptions,
+) => string
+
+type StripFn = (str: string, opts?: GenerateOptions) => string
+
+type TitleizeFn = (str: string, options?: GenerateOptions) => string
+
+/**
+ * FilterFn: returns truthy to include the item, falsy to exclude it.
+ * The return value is checked for truthiness, not used as a replacement.
+ * */
+export type FilterFn = (content: string, ele: Token, arr: Token[]) => string
+
+export interface Token {
+  content: string
+  type?: string
+  lvl: number
+  hLevel: number
+  i?: number
+  seen?: number
+  slug?: string
+  children?: Token[]
+  lines: number[]
+}
+
+export interface JsonToken {
+  content: string
+  slug: string
+  lvl: number
+  i?: number
+  seen: number
+}
+
+export function generate(options?: GenerateOptions): any {
+  const opts = { ...{ firsth1: true, maxdepth: 6 }, ...options }
+  const stripFirst = opts.firsth1 === false
+  if (opts.linkify === undefined) opts.linkify = true
+
+  return function (md: RemarkablePlus) {
+    md.renderer.render = function (tokens: Token[]) {
+      const copiedTokens = [...tokens]
+      const seen: { [key: string]: number } = {}
+      let tocstart = -1
+      const arr: Token[] = []
+      const res: {
+        json?: JsonToken[]
+        highest?: number
+        tokens?: Token[]
+        content?: string
+      } = {}
+
+      for (let i = 0; i < copiedTokens.length; i++) {
+        const token = copiedTokens[i]
+        if (/<!--[ \t]*toc[ \t]*-->/.test(token.content)) {
+          tocstart = token.lines[1]
+        }
+
+        if (token.type === "heading_open") {
+          copiedTokens[i + 1].lvl = copiedTokens[i].hLevel
+          copiedTokens[i + 1].i = i
+          arr.push(copiedTokens[i + 1])
+        }
+      }
+
+      let result: Token[] = []
+      res.json = []
+
+      for (const tok of arr) {
+        if (tok.lines && tok.lines[0] > tocstart) {
+          let val = tok.content
+          if (seen[val] === undefined) seen[val] = 0
+          if (tok.children && tok.children[0].type === "link_open") {
+            if (tok.children[1].type === "text") {
+              val = tok.children[1].content
+            }
+          }
+
+          tok.seen = seen[val]
+          tok.slug = slugify(val, opts)
+          const jsonToken: JsonToken = {
+            content: tok.content,
+            slug: seen[val] === 0 ? tok.slug : `${tok.slug}-${seen[val]}`,
+            lvl: tok.lvl,
+            i: tok.i,
+            seen: tok.seen,
+          }
+          res.json.push(jsonToken)
+
+          if (opts.linkify) {
+            const tokLinkified = linkify(tok, opts)
+            result.push(tokLinkified)
+          } else {
+            result.push(tok)
+          }
+
+          seen[val] += 1
+        }
+      }
+
+      if (stripFirst && result.length > 0 && result[0].lvl === 1) {
+        result = result.slice(1)
+        res.json = res.json.slice(1)
+      }
+      opts.highest = highest(result)
+      res.highest = opts.highest
+      res.tokens = copiedTokens
+
+      const { out, bList: _bList } = bullets(result, opts)
+      res.content = out
+      if (opts.append) res.content += opts.append
+      return res
+    }
+  }
+}
+
+/** ListItemFn: Func that creates a single markdown list item for the Toc. */
+type ListItemFn = (level: number, content: string) => string
+
+const isListItemFn = (fn: any): fn is ListItemFn => {
+  if (typeof fn !== "function") {
+    return false // wrong type of object
+  } else if (fn.length !== 2) {
+    return false // wrong number of args
+  }
+
+  try {
+    const tempResult = fn(1, "test")
+    return typeof tempResult === "string"
+  } catch (_error) {
+    // If calling the func throws an error, it's not a ListItemFn
+    return false
+  }
+}
+
+const newListitemFn = (
+  opts: GenerateOptions,
+  fn: FilterFn | null,
+): ListItemFn => {
+  const liFn = listitem(opts, fn as Function)
+  if (isListItemFn(liFn)) return liFn
+  throw Error(`list item fn has the wrong type ${JSON.stringify(liFn)}`)
+}
+
+/**
+ * Render markdown list bullets
+ *
+ * @param  {Array} `arr` Array of Toc `Token` items
+ * @param  {GenerateOptions} `options`
+ * @return  {Object} `{ out: string; bList: BulletList }`, where
+ *   - `out` is the Toc output string with bullets
+ *   - `bList`: Structured object version of `out`. Great for debugging.
+ */
+export function bullets(
+  arr: Token[],
+  options?: GenerateOptions,
+): { out: string; bList: BulletList } {
+  const opts = {
+    indent: "  ",
+    ...options,
+  }
+
+  opts.chars = opts.chars || opts.bullets || ["-", "*", "+"]
+
+  const fn = typeof opts.filter === "function" ? opts.filter : null
+  const li: ListItemFn = newListitemFn(opts, fn)
+
+  const includeFirstH1 = opts.firsth1 === true
+  return new BulletsParser(arr).bullets(includeFirstH1, fn, li, opts)
+}
+
+interface IBulletState {
+  firstIsH1: null | boolean
+  numH1s: number
+  noTokens: boolean
+  soloToken: boolean
+  tokens: Token[]
+}
+
+type BulletList = { bullet: string; lvl: number; content: string }[]
+
+export class BulletsParser implements IBulletState {
+  firstIsH1: null | boolean
+  numH1s: number
+  noTokens: boolean
+  soloToken: boolean
+  tokens: Token[]
+  hs: { lvl: number; content: string }[]
+
+  constructor(tokens: Token[]) {
+    this.noTokens = tokens.length === 0
+    this.soloToken = tokens.length === 1
+    this.firstIsH1 = null
+    this.numH1s = 0
+    this.tokens = tokens
+    this.hs = []
+    if (tokens.length < 2) return
+    this.parseTokens()
+  }
+
+  parseTokens = (): void => {
+    // TODO: Useful debug for feature development
+    // console.debug("DEBUG parseTokens: %o", this.tokens)
+    this.tokens.forEach((token, idx) => {
+      const isH1 = token.lvl === 1
+      if (isH1) this.numH1s += 1
+      if (idx === 0) {
+        this.firstIsH1 = isH1
+      }
+    })
+  }
+
+  otherH1sPresent = (): boolean => {
+    if (this.numH1s === 0) return false
+    else if (this.firstIsH1 && this.numH1s > 1) return true
+    else if (!this.firstIsH1 && this.numH1s > 0) return true
+    return false
+  }
+
+  bulletList = (
+    includeFirstH1: boolean,
+    fn: FilterFn | null,
+    li: ListItemFn,
+    opts: GenerateOptions,
+  ): BulletList => {
+    // TODO: Useful debug for feature development
+    // const indent: boolean = this.indent(includeFirstH1)
+    const unindent: number = !this.indent(includeFirstH1) ? 1 : 0
+    // console.debug("DEBUG obj: %o", { includeFirstH1, unindent, indent })
+    const bList: BulletList = []
+    this.tokens.forEach((ele) => {
+      ele.lvl -= unindent
+
+      if (fn && !fn(ele.content, ele, this.tokens)) {
+        return
+      }
+
+      const maxDepth = opts.maxdepth ?? 3
+      // console.debug("DEBUG obj: %o", { opts, maxDepth, tokens: this.tokens })
+      if (ele.lvl > maxDepth) {
+        return
+      }
+
+      // generate() sets highest before rendering the bullet list.
+      const lvl = ele.lvl - opts.highest!
+      const { content } = ele
+      bList.push({ bullet: li(lvl, content), lvl, content })
+    })
+    return bList
+  }
+
+  bullets = (
+    includeFirstH1: boolean,
+    fn: FilterFn | null,
+    li: ListItemFn,
+    opts: GenerateOptions,
+  ): { out: string; bList: BulletList } => {
+    const bList = this.bulletList(includeFirstH1, fn, li, opts)
+    return {
+      out: bList.map((item) => item.bullet).join("\n"),
+      bList,
+    }
+  }
+
+  // assume arr.length >=  2   -> 2 headings
+  //
+  // case: h1, h2, ..., h1, ... -> indent
+  // "first is h1" AND "other h1s present"
+  //
+  // case: h2, h2, ... -> unindent
+  // NOT "first is h1" AND NOT "other h1s present"
+  //
+  // case: h1, h2, ... -> if includeFirstH1 ? indent : unindent
+  // "first is h1" AND NOT "other h1s present"
+  //
+  // case: h2, ..., h1, ...  -> indent
+  // NOT "first is h1" AND "other h1s present"
+  //
+  // case: arr.length = 0   -> error
+  // case: arr.length = 1   -> unindent
+  indent = (includeFirstH1: boolean): boolean => {
+    const { firstIsH1 } = this
+    const otherH1sPresent = this.otherH1sPresent()
+
+    // TODO: Useful debug for feature development
+    // console.debug("DEBUG obj: %o", { otherH1sPresent, firstIsH1 })
+
+    if (firstIsH1 && otherH1sPresent) return true
+    else if (firstIsH1 && !otherH1sPresent) return includeFirstH1 ? true : false
+    else if (!firstIsH1 && otherH1sPresent) return true
+    else if (!firstIsH1 && !otherH1sPresent) return true
+    else return false
+    // if (this.soloToken) return false
+    // if (this.noTokens) return false
+  }
+}
+
+/**
+ * Get the highest heading level in the array, so we can un-indent the proper
+ * number of levels. For example, a document with an "h1" heading has highest=1.
+ * If the topmost heading is an h2, then highest is 2.
+ *
+ * @param {Array} `arr` Array of tokens
+ * @return {Number} Highest level
+ */
+export function highest(arr: Token[]): number {
+  const sorted = arr.slice().sort((a, b) => a.lvl - b.lvl)
+
+  return sorted.length ? sorted[0].lvl : 0
+}
+
+/**
+ * Turn headings into anchors
+ */
+export function linkify(tok: Token, options?: GenerateOptions): Token {
+  const opts = { ...options }
+  if (tok && tok.content) {
+    opts.num = tok.seen
+    const text = titleize(tok.content, opts)
+    const slug = slugify(tok.content, opts)
+    const escapedSlug = querystring.escape(slug)
+
+    // console.debug("DEBUG linkfiy: %o", { escapedSlug, opts, tok, text, slug, })
+    let linkifyFunc: LinkifyFn = (_tok, text, escapedSlug, _opts) =>
+      markdownLink(text, `#${escapedSlug}`)
+    if (opts && typeof opts.linkify === "function") {
+      linkifyFunc = opts.linkify
+    }
+    tok.content = linkifyFunc(tok, text, escapedSlug, opts)
+  }
+  return tok
+}
+/**
+ * Titleize the title part of a markdown link.
+ */
+export function titleize(str: string, opts?: GenerateOptions): string {
+  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 = getTitle(str)
+
+  str = str.split(/<\/?[^>]+>/).join("")
+
+  str = str.split(/[ \t]+/).join(" ")
+
+  return str.trim()
+}
+
+/**
+ * Optionally strip specified words from heading text (not url)
+ */
+export function strip(str: string, opts?: GenerateOptions): string {
+  if (!opts) return str
+  if (!opts.strip) return str
+
+  if (typeof opts.strip === "function") {
+    return opts.strip(str, opts)
+  }
+
+  if (Array.isArray(opts.strip) && opts.strip.length) {
+    const res = opts.strip.join("|")
+    const re = new RegExp(res, "g")
+    str = str.trim().replace(re, "")
+    return str.replace(/^-|-$/g, "")
+  }
+
+  return str
+}

package/src/mdtoc/index.ts

@@ -0,0 +1,13 @@
+import concat from "concat-stream"
+import minimist from "minimist"
+import { generate, insert, strip } from "./generate"
+
+export { getTitle, slugify, replaceDiacritics } from "./options"
+export { toc } from "./toc"
+export const Toc = {
+  insert,
+  strip,
+  plugin: generate,
+}
+
+export { minimist, concat }

package/src/mdtoc/insert.ts

@@ -0,0 +1,125 @@
+import matter from "gray-matter"
+import { type SlugifyOptions } from "./options"
+import { toc } from "./toc"
+
+function split(str: string, re: RegExp) {
+  return str.split(re).map(trim)
+}
+
+function trim(str: string) {
+  return str.trim()
+}
+
+interface InsertOptions extends SlugifyOptions {
+  /**  Regex to find toc insertion points  */
+  regex?: RegExp
+
+  /** Opening tag for toc */
+  open?: string
+
+  /** Closing tag for toc */
+  close?: string
+
+  /** Custom toc content to insert */
+  toc?: string
+
+  linkify?: boolean
+}
+
+const defaultInsertOptions: InsertOptions = {
+  regex: /(?:<!-- toc(?:\s*stop)? -->)/g,
+  open: "<!-- toc -->\n",
+  close: "<!-- tocstop -->",
+}
+
+/**
+ * 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
+ */
+export function insert(str: string, options?: InsertOptions): string {
+  options = { ...defaultInsertOptions, ...options }
+
+  let { close } = options
+  const { regex, open } = options
+  if (!close) close = defaultInsertOptions.close!
+
+  let newlines = ""
+  const m = /\n+$/.exec(str)
+  if (m) newlines = m[0]
+
+  let obj: MatterFile | null = null
+  // does the file have front-matter?
+  if (/^---/.test(str)) {
+    // extract it temporarily so the syntax
+    // doesn't get mistaken for a heading
+    obj = grayMatter(str)
+    str = obj.content
+  }
+
+  const sections = split(str, regex ?? defaultInsertOptions.regex!)
+  if (sections.length > 3) {
+    throw new Error(
+      "markdown-toc only supports one Table of Contents per file.",
+    )
+  }
+
+  const last = sections[sections.length - 1]
+  if (sections.length === 3 || sections.length === 2) {
+    const body = options.toc || toc(last, options).content
+    const block = `${open}${body}\n${close}`
+    if (sections.length === 3) {
+      sections.splice(1, 1, block)
+    } else {
+      sections.splice(1, 0, block)
+    }
+  }
+
+  const resultString = sections.join("\n\n") + newlines
+  // if front-matter was found, put it back now
+  if (obj) {
+    return matter.stringify(resultString, obj.data)
+  }
+  return resultString
+}
+
+const grayMatter = (
+  str: string,
+  options?: matter.GrayMatterOption,
+): MatterFile => matter(str, options) as MatterFile
+
+/**
+ * Object returned by the `matter` function from "gray-matter"
+ */
+export interface MatterFile {
+  /** Parsed front matter data */
+  data: { [key: string]: any }
+
+  /** Content string without front matter */
+  content: string
+
+  /** Excerpt extracted from content */
+  excerpt: string
+
+  /** Original unmodified input */
+  orig: string
+
+  /** Language defined in front matter */
+  language?: string
+
+  /** Raw front matter string */
+  matter?: string
+
+  /** File path if read from the file system */
+  path?: string
+}
+
+// function split(str, re) {
+//   return str.split(re).map(trim);
+// }

package/src/mdtoc/options.ts

@@ -0,0 +1,73 @@
+/**
+ * src/mdtoc/options.ts
+ */
+import stripColor from "strip-color"
+import diacritics from "diacritics-map"
+
+export { getTitle, replaceDiacritics, slugify, defaultOptions }
+export interface SlugifyOptions {
+  slugify?: SlugifyFn | boolean
+  stripHeadingTags?: boolean
+  num?: number
+}
+
+export type SlugifyFn = (str: string, options: SlugifyOptions) => string
+
+/**
+ * Get the "title" from a markdown link
+ */
+function getTitle(str: string): string {
+  if (/^\[[^\]]+\]\(/.test(str)) {
+    const m = /^\[([^\]]+)\]/.exec(str)
+    if (m) return m[1]
+  }
+  return str
+}
+
+const defaultOptions: SlugifyOptions = {
+  slugify: (str: string, _options: SlugifyOptions) => str,
+  stripHeadingTags: false,
+  num: undefined,
+}
+
+/**
+ * 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
+ */
+function slugify(str: string, options?: SlugifyOptions): string {
+  if (!options) options = defaultOptions
+
+  if (options.slugify === false) return str
+  if (typeof options.slugify === "function") {
+    return options.slugify(str, options)
+  }
+
+  str = getTitle(str)
+  str = 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: string) {
+  return str.replace(/[À-ž]/g, (ch) => diacritics[ch] || ch)
+}

package/src/mdtoc/remarkable.ts

@@ -0,0 +1,168 @@
+/**
+ * src/mdtoc/remarkable.ts
+ */
+import { Remarkable } from "remarkable"
+
+export interface IRemarkable extends RemarkableComponents {
+  // constructor(preset?: string, options?: RemarkableOptions): IRemarkable;
+
+  /**
+   * Set options as an alternative to passing them
+   * to the constructor.
+   *
+   * ```js
+   * md.set({typographer: true});
+   * ```
+   * @param {Object} `options`
+   * @api public
+   */
+  set(options: RemarkableOptions): void
+
+  /**
+   * Batch loader for components rules states, and options
+   *
+   * @param  {Object} `presets`
+   */
+  configure(presets: RemarkablePresets): void
+
+  /**
+   * Use a plugin.
+   *
+   * ```js
+   * var md = new Remarkable();
+   *
+   * md.use(plugin1)
+   *   .use(plugin2, opts)
+   *   .use(plugin3);
+   * ```
+   *
+   * @param  {Function} `plugin`
+   * @param  {Object} `options`
+   * @return {Object} `Remarkable` for chaining
+   */
+  use(plugin: Remarkable.Plugin, options?: RemarkableOptions): IRemarkable
+
+  /**
+   * Parse the input `string` and return a tokens array.
+   * Modifies `env` with definitions data.
+   *
+   * @param  {String} `str`
+   * @param  {Object} `env`
+   * @return {Array} Array of tokens
+   */
+  parse(str: string, env?: RemarkableEnv): any[]
+
+  /**
+   * The main `.render()` method that does all the magic :)
+   *
+   * @param  {String} `str`
+   * @param  {Object} `env`
+   * @return {string} Rendered HTML.
+   */
+  render(str: string, env?: RemarkableEnv): string
+
+  /**
+   * Parse the given content `string` as a single string.
+   *
+   * @param  {String} `str`
+   * @param  {Object} `env`
+   * @return {Array} Array of tokens
+   */
+  parseInline(str: string, env?: RemarkableEnv): any[]
+
+  /**
+   * Render a single content `string`, without wrapping it
+   * to paragraphs
+   *
+   * @param  {String} `str`
+   * @param  {Object} `env`
+   * @return {String}
+   */
+  renderInline(str: string, env?: RemarkableEnv): string
+
+  renderer: any
+  ruler: any
+  options: RemarkableOptions
+}
+
+export interface RemarkableOptions {
+  html?: boolean
+  xhtmlOut?: boolean
+  breaks?: boolean
+  langPrefix?: string
+  linkTarget?: string
+  typographer?: boolean
+  quotes?: string
+  highlight?: (str: string, lang: string) => string
+  maxNesting?: number
+}
+
+interface RemarkableComponents {
+  core: any
+  block: any
+  inline: any
+}
+
+type RemarkableEnv = Remarkable.Env
+
+type RemarkablePresets = Remarkable.Presets
+
+export class RemarkablePlus implements IRemarkable, RemarkableComponents {
+  // Remarkable exposes these fields at runtime, but @types/remarkable omits them.
+  core: Remarkable & { ruler: unknown; options: RemarkableOptions }
+
+  constructor({
+    preset,
+    options,
+  }: {
+    preset?: "default" | "full" | "commonmark"
+    options?: RemarkableOptions
+  }) {
+    const core = new Remarkable(preset ?? "default", options)
+    this.core = core as typeof this.core
+  }
+
+  set = (options: RemarkableOptions): void => {
+    this.core.set(options)
+  }
+
+  configure = (presets: RemarkablePresets): void => {
+    this.core.configure(presets)
+  }
+
+  use = (plugin: Remarkable.Plugin, options?: RemarkableOptions): IRemarkable => {
+    this.core.use(plugin, options)
+    return this // Return `this` to allow for chaining.
+  }
+
+  parse = (str: string, env?: RemarkableEnv): any[] => this.core.parse(str, env ?? {})
+
+  render = (str: string, env?: RemarkableEnv): string =>
+    this.core.render(str, env)
+
+  parseInline = (str: string, env?: RemarkableEnv): any[] =>
+    this.core.parseInline(str, env ?? {})
+
+  renderInline = (str: string, env?: RemarkableEnv): string =>
+    this.core.renderInline(str, env)
+
+  get inline(): any {
+    return this.core.inline
+  }
+
+  get block(): any {
+    return this.core.block
+  }
+
+  get renderer(): any {
+    return this.core.renderer
+  }
+
+  get ruler(): any {
+    return this.core.ruler
+  }
+
+  get options(): RemarkableOptions {
+    return this.core.options
+  }
+}

package/src/mdtoc/toc.ts

@@ -0,0 +1,41 @@
+import { type GenerateOptions, type Token, generate } from "./generate"
+import { RemarkablePlus } from "./remarkable"
+
+/**
+ * Generates a table of contents (TOC) from markdown headings.
+ *
+ * @param {string} markdown - Markdown string to generate TOC from
+ * @param {GenerateOptions} opts - Options for TOC generation
+ * @returns {TocResult} TOC result
+ */
+export const toc = (markdown: string, opts?: GenerateOptions): TocResult =>
+  new RemarkablePlus({})
+    .use(generate(opts))
+    .render(markdown) as unknown as TocResult
+
+/** Table of contents (TOC) result */
+export interface TocResult {
+  /** Rendered TOC content string */
+  content: string
+
+  /** Highest heading level found */
+  highest: number
+
+  /** Array of markdown AST tokens */
+  tokens: Token[]
+
+  /** Array of heading objects */
+  json: Heading[]
+}
+
+/** Heading object */
+interface Heading {
+  /** Heading content text */
+  content: string
+
+  /** Heading level */
+  lvl: number
+
+  /** Slugified head ID */
+  slug: string
+}

package/src/vendor.d.ts

@@ -0,0 +1,15 @@
+declare module "markdown-link" {
+  export default function link(anchor: string, href: string, title?: string): string
+}
+
+declare module "list-item" {
+  export default function listItem(
+    options: { indent?: string; chars?: string | string[]; nobullet?: boolean },
+    transform?: Function | null,
+  ): (level: number, content: string) => string
+}
+
+declare module "diacritics-map" {
+  const diacritics: Record<string, string>
+  export default diacritics
+}