remark-flexible-toc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 ipikuka
+
+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,413 @@
+# remark-flexible-toc
+
+[![NPM version][npm-image]][npm-url]
+[![Build][github-build]][github-build-url]
+![npm-typescript]
+[![License][github-license]][github-license-url]
+
+This package is a [unified][unified] ([remark][remark]) plugin to expose the table of contents via Vfile.data or via an option reference (compatible with new parser "[micromark][micromark]").
+
+"**unified**" is a project that transforms content with abstract syntax trees (ASTs). "**remark**" adds support for markdown to unified. "**mdast**" is the markdown abstract syntax tree (AST) that remark uses.
+
+**This plugin is a remark plugin that gets info from the mdast.**
+
+## When should I use this?
+
+This plugin `remark-flexible-toc` is useful if you want to get the table of contents (TOC) from the markdown/MDX document. The `remark-flexible-toc` exposes the table of contents (TOC) in two ways:
++ by adding the `toc` into the Vfile.data
++ by mutating an array of reference if provided in the options
+
+## Installation
+
+This package is suitable for ESM only. In Node.js (version 16+), install with npm:
+
+```bash
+npm install remark-flexible-toc
+```
+
+or
+
+```bash
+yarn add remark-flexible-toc
+```
+
+## Usage
+
+Say we have the following file, `example.md`, which consists some headings.
+
+```markdown
+# The Main Heading
+
+## Section
+
+### Subheading 1
+
+### Subheading 2
+```
+
+And our module, `example.js`, looks as follows:
+
+```javascript
+import { read } from "to-vfile";
+import remark from "remark";
+import gfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeStringify from "rehype-stringify";
+import remarkFlexibleToc from "remark-flexible-toc";
+
+main();
+
+async function main() {
+  const toc = [];
+
+  const file = await remark()
+    .use(gfm)
+    .use(remarkFlexibleToc, {tocRef: toc})
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .process(await read("example.md"));
+
+  // the first way of getting the table of contents (TOC) via file.data
+  console.log(file.data.toc);
+
+  // the second way of getting the table of contents (TOC), since we provided an array of reference in the options
+  console.log(toc);
+}
+```
+
+Now, running `node example.js` you see that the same table of contents is logged in the console:
+
+```javascript
+[
+  {
+    depth: 2,
+    href: "#section",
+    numbering: [1, 1],
+    parent: "root",
+    value: "Section",
+  },
+  {
+    depth: 3,
+    href: "#subheading-1",
+    numbering: [1, 1, 1],
+    parent: "root",
+    value: "Subheading 1",
+  },
+  {
+    depth: 3,
+    href: "#subheading-2",
+    numbering: [1, 1, 2],
+    parent: "root",
+    value: "Subheading 2",
+  },
+]
+```
+
+Without `remark-flexible-toc`, there wouldn't be any `toc` key in the `file.data`:
+
+## Options
+
+All options are **optional**.
+
+```typescript
+type HeadingParent =
+  | "root"
+  | "blockquote"
+  | "footnoteDefinition"
+  | "listItem"
+  | "container"
+  | "mdxJsxFlowElement";
+
+type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+
+use(remarkFlexibleToc, {
+  tocName?: string; // default: "toc"
+  tocRef?: TocItem[]; // default: []
+  maxDepth?: HeadingDepth; // default: 6
+  skipLevels?: HeadingDepth[]; // default: [1]
+  skipParents?: Exclude<HeadingParent, "root">[]; // default: []
+  exclude?: string | string[]; // default is undefined
+  prefix?: string; // default is undefined
+  fallback?: (toc: TocItem[]) => undefined; // default is undefined
+} as FlexibleTocOptions);
+```
+
+#### `tocName`
+
+It is a **string** option in which the table of contents (TOC) is placed in the `vfile.data`. 
+
+By default it is **`toc`**, meaningly the TOC is reachable via `vfile.data.toc`.
+
+```javascript
+use(remarkFlexibleToc, {
+  tocName: "headings";
+});
+```
+Now, the TOC is accessable via `vfile.data.headings`.
+
+#### `tocRef`
+
+It is an **array of reference** option for getting the table of contents (TOC), which is the second way of getting the TOC from the `remark-flexible-toc`.
+
+The reference array should be an empty array, if not, it is emptied by the plugin.
+
+If you use _typescript_, the array reference should be `const toc: TocItem[] = []`.
+
+```javascript
+const toc = [];
+
+use(remarkFlexibleToc, {
+  tocRef: toc; // the `remark-flexible-toc` mutates the array of reference
+});
+```
+
+Now, the TOC is accessable via `toc`.
+
+#### `maxDepth`
+
+It is a **number** option for indicating the max heading depth to include in the TOC.
+
+By default it is `6`. Meaningly, there is no restriction by default.
+
+```javascript
+use(remarkFlexibleToc, {
+  maxDepth: 4;
+});
+```
+
+The `maxDepth` option is inclusive: when set to 4, level fourth headings are included, but fifth and sixth level headings will be skipped.
+
+#### `skipLevels` 
+
+It is an **array** option to indicate the heading levels to be skipped. 
+
+By default it is `[1]` since the first level heading is not expected to be in the TOC.
+
+```javascript
+use(remarkFlexibleToc, {
+  skipLevels: [1, 2, 4, 5, 6];
+});
+```
+
+Now, the TOC consists only the third level headings.
+
+#### `skipParents`
+
+By default it is an empty array `[]`. The array may contain the parent values `blockquote`, `footnoteDefinition`, `listItem`, `container`, `mdxJsxFlowElement`.
+
+```javascript
+use(remarkFlexibleToc, {
+  skipParents: ["blockquote"];
+});
+```
+
+Now, the headings in the `<blockquote>` will not be added into the TOC.
+
+#### `exclude`
+
+It is a **string** or **string[]** option. The plugin wraps the string(s) in new RegExp('^(' + value + ')$', 'i'), so any heading matching this expression will not be present in the TOC. The RegExp checks exact (not contain) matching and case insensitive as you see.
+
+The option has no default value.
+
+```javascript
+use(remarkFlexibleToc, {
+  exclude: "The Subheading";
+});
+```
+Now, the heading "The Subheading" will not be included in to the TOC, but forexample "The Subheading Something" will be included.
+
+#### `prefix`
+
+It is a **string** option to add a prefix to `href`s of the TOC items. It is useful for example when later going from markdown to HTML and sanitizing with `rehype-sanitize`.
+
+The option has no default value.
+
+```javascript
+use(remarkFlexibleToc, {
+  prefix: "text-prefix-";
+});
+```
+Now, all TOC items' `href`s will start with that prefix like `#text-prefix-the-subheading`.
+
+#### `callback`
+
+It is a **callback function** `callback?: (toc: TocItem[]) => undefined;` which takes the TOC items as an argument and returns nothing. It is usefull for logging the TOC, forexample, or modifing the TOC. **It is allowed that the callback function is able mutate the TOC items !.**
+
+The option has no default value.
+
+```javascript
+use(remarkFlexibleToc, {
+  callback: (toc) => {
+    console.log(toc);
+  };
+});
+```
+
+Now, each time when you compile the source, the TOC will be logged into console for debugging purpose.
+
+## A Table of Content (TOC) Item
+
+```typescript
+type TocItem = {
+  value: string; // heading text
+  href: string; // produced uniquely by "github-slugger" using the value of the heading
+  depth: HeadingDepth; // 1 | 2 | 3 | 4 | 5 | 6
+  numbering: number[]; // explained below
+  parent: HeadingParent; // "root"| "blockquote" | "footnoteDefinition" | "listItem" | "container" | "mdxJsxFlowElement"
+  data?: Record<string, unknown>; // Other remark plugins can store custom data in "node.data.hProperties" like "id" etc.
+};
+```
+
+As a note, the `remark-flexible-toc` uses the `github-slugger` internally for producing unique links. Then, it is possible you to use [`rehype-slug`](https://github.com/rehypejs/rehype-slug) (forIDs on headings) and [`rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings) (for anchors that link-to-self) because they use the same `github-slugger`.
+
+As an example for the unique heading links (notice the same heading texts).
+
+```markdown
+# The Main Heading
+
+## Section
+
+### Subheading
+
+## Section
+      
+### Subheading
+```
+
+The `github-slugger` produces unique links with using a counter mechanism internally, and the TOC item's `href`s is going to be unique.
+
+```javascript
+[
+  {
+    depth: 2,
+    href: "#section",
+    numbering: [1, 1],
+    parent: "root",
+    value: "Section",
+  },
+  {
+    depth: 3,
+    href: "#subheading",
+    numbering: [1, 1, 1],
+    parent: "root",
+    value: "Subheading",
+  },
+  {
+    depth: 2,
+    href: "#section-1",
+    numbering: [1, 2],
+    parent: "root",
+    value: "Section",
+  },
+  {
+    depth: 3,
+    href: "#subheading-1",
+    numbering: [1, 2, 1],
+    parent: "root",
+    value: "Subheading",
+  },
+]
+```
+
+## Numbering for Ordered Table of Contents
+
+The `remark-flexible-toc` produces always the `numbering` for the TOC items in case you show the ordered TOC.
+
+The **numbering** of a TOC item is an array of number. The numbers in the `numbering` corresponds the **level of the headers**. With that structure, you know which header is under which header.
+
+```js
+[1, 1]
+[1, 2]
+[1, 2, 1]
+[1, 2, 2]
+[1, 3]
+```
+
+The first number of the `numbering` is related with the fist level headings.
+The second number of the `numbering` is related with the second level headings.
+And so on...
+
+If yo haven't included the first level header into the TOC, you can slice the `numbering` with `1` so as to second level headings starts with `1` and so on..
+
+```javascript
+tocItem.numbering.slice(1);
+```
+
+You can join the `numbering` as you wish. It is up to you to combine the `numbering` with dot, or dash.
+
+```javascript
+tocItem.numbering.join(".");
+tocItem.numbering.join("-");
+```
+
+## Syntax tree
+
+This plugin does not modify the `mdast` (markdown abstract syntax tree), collects data from the `mdast` and adds information into the `vfile.data` if required.
+
+## Types
+
+This package is fully typed with [TypeScript][typeScript].
+
+The plugin exports the types `FlexibleTocOptions`, `HeadingParent`, `HeadingDepth`, `TocItem`.
+
+## Compatibility
+
+This plugin works with unified version 6+ and remark version 7+. It is compatible with MDX version.3.
+
+## Security
+
+Use of `remark-flexible-toc` does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.
+
+## My Plugins
+
+### My Remark Plugins
+
++ [`remark-flexible-code-titles`](https://www.npmjs.com/package/remark-flexible-code-titles)
+  – Remark plugin to add titles or/and containers for the code blocks with customizable properties
++ [`remark-flexible-containers`](https://www.npmjs.com/package/remark-flexible-containers)
+  – Remark plugin to add custom containers with customizable properties in markdown
++ [`remark-ins`](https://www.npmjs.com/package/remark-ins)
+  – Remark plugin to add `ins` element in markdown
++ [`remark-flexible-paragraphs`](https://www.npmjs.com/package/remark-flexible-paragraphs)
+  – Remark plugin to add custom paragraphs with customizable properties in markdown
++ [`remark-flexible-markers`](https://www.npmjs.com/package/remark-flexible-markers)
+  – Remark plugin to add custom `mark` element with customizable properties in markdown
++ [`remark-flexible-toc`](https://www.npmjs.com/package/remark-flexible-toc)
+  – Remark plugin to expose the table of contents via Vfile.data or via an option reference
+
+### My Recma Plugins
+
++ [`recma-mdx-escape-missing-components`](https://www.npmjs.com/package/recma-mdx-escape-missing-components)
+  – Recma plugin to to set the default value `() => null` for the Components in MDX in case of missing or not provided
++ [`recma-mdx-change-props`](https://www.npmjs.com/package/recma-mdx-change-props)
+  – Recma plugin to change the 'props' parameter into '_props' in the function '_createMdxContent' in the compiled source in order to be able to use {props.foo} like expressions for the `next-mdx-remote` or `next-mdx-remote-client` users.
+
+## License
+
+[MIT][license] © ipikuka
+
+### Keywords
+
+[unified][unifiednpm] [remark][remarknpm] [remark-plugin][remarkpluginnpm] [mdast][mdastnpm] [markdown][markdownnpm] [mdxnpm][mdxnpm] [remark toc][remarktocnpm] [remark table of contents][remarktableofcontentsnpm]
+
+[unified]: https://github.com/unifiedjs/unified
+[unifiednpm]: https://www.npmjs.com/search?q=keywords:unified
+[remark]: https://github.com/remarkjs/remark
+[remarknpm]: https://www.npmjs.com/search?q=keywords:remark
+[remarkpluginnpm]: https://www.npmjs.com/search?q=keywords:remark%20plugin
+[mdast]: https://github.com/syntax-tree/mdast
+[mdastnpm]: https://www.npmjs.com/search?q=keywords:mdast
+[micromark]: https://github.com/micromark/micromark
+[typescript]: https://www.typescriptlang.org/
+[license]: https://github.com/ipikuka/remark-flexible-toc/blob/main/LICENSE
+[mdxnpm]: https://www.npmjs.com/search?q=keywords:mdx
+[markdownnpm]: https://www.npmjs.com/search?q=keywords:markdown
+[remarktocnpm]: https://www.npmjs.com/search?q=keywords:remark%20toc
+[remarktableofcontentsnpm]: https://www.npmjs.com/search?q=keywords:remark%20table%20of%20contents
+[npm-url]: https://www.npmjs.com/package/remark-flexible-toc
+[npm-image]: https://img.shields.io/npm/v/remark-flexible-toc
+[github-license]: https://img.shields.io/github/license/ipikuka/remark-flexible-toc
+[github-license-url]: https://github.com/ipikuka/remark-flexible-toc/blob/master/LICENSE
+[github-build]: https://github.com/ipikuka/remark-flexible-toc/actions/workflows/publish.yml/badge.svg
+[github-build-url]: https://github.com/ipikuka/remark-flexible-toc/actions/workflows/publish.yml
+[npm-typescript]: https://img.shields.io/npm/types/remark-flexible-toc

package/dist/esm/index.d.ts

@@ -0,0 +1,38 @@
+import { type Plugin } from "unified";
+import { type Root } from "mdast";
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type PartiallyRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+export type HeadingParent = "root" | "blockquote" | "footnoteDefinition" | "listItem" | "container" | "mdxJsxFlowElement";
+export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+export type TocItem = {
+    value: string;
+    href: string;
+    depth: HeadingDepth;
+    numbering: number[];
+    parent: HeadingParent;
+    data?: Record<string, unknown>;
+};
+/**
+ * tocName (default: "toc") - the key name which is attached into vfile.data
+ * tocRef (default: []) — another way of exposing the tocItems
+ * maxDepth (default: 6) — max heading depth to include in the table of contents; this is inclusive: when set to 3, level three headings are included
+ * skipLevels (default: [1]) — disallowed heading levels, by default the article h1 is not expected to be in the TOC
+ * skipParents (default: []) — disallow headings to be children of certain node types, (the "root" can not be skipped)
+ * exclude — headings to skip, wrapped in new RegExp('^(' + value + ')$', 'i'); any heading matching this expression will not be present in the table of contents
+ * prefix - the text that will be attached to headings as prefix, like "text-prefix-"
+ * callback - It is a callback function to take the array of toc items as an argument
+ */
+export type FlexibleTocOptions = {
+    tocName?: string;
+    tocRef?: TocItem[];
+    maxDepth?: HeadingDepth;
+    skipLevels?: HeadingDepth[];
+    skipParents?: Exclude<HeadingParent, "root">[];
+    exclude?: string | string[];
+    prefix?: string;
+    callback?: (toc: TocItem[]) => undefined;
+};
+declare const RemarkFlexibleToc: Plugin<[FlexibleTocOptions?], Root>;
+export default RemarkFlexibleToc;

package/dist/esm/index.js

@@ -0,0 +1,111 @@
+import { visit, CONTINUE } from "unist-util-visit";
+import GithubSlugger from "github-slugger";
+import { toString } from "mdast-util-to-string";
+const DEFAULT_SETTINGS = {
+    tocName: "toc",
+    tocRef: [],
+    maxDepth: 6,
+    skipLevels: [1],
+    skipParents: [],
+};
+/**
+ * adds numberings to the TOC items.
+ * why "number[]"? It is because up to you joining with dot or dash or slicing the first number (reserved for h1)
+ *
+ * [1]
+ * [1,1]
+ * [1,2]
+ * [1,2,1]
+ */
+function addNumbering(arr) {
+    for (let i = 0; i < arr.length; i++) {
+        const tocItem = arr[i];
+        const depth = tocItem.depth;
+        let numbering = [];
+        const prevObj = i > 0 ? arr[i - 1] : undefined;
+        const prevDepth = prevObj ? prevObj.depth : undefined;
+        const prevNumbering = prevObj ? prevObj.numbering : undefined;
+        if (!prevNumbering || !prevDepth) {
+            numbering = Array.from({ length: depth }, () => 1);
+        }
+        else if (depth === prevDepth) {
+            numbering = [...prevNumbering];
+            numbering[depth - 1]++;
+        }
+        else if (depth > prevDepth) {
+            numbering = [
+                ...prevNumbering,
+                ...Array.from({ length: depth - prevDepth }, // if depth is more bigger than prevDepth, put more "1" inside the array
+                () => 1),
+            ];
+        }
+        else if (depth < prevDepth) {
+            numbering = prevNumbering.slice(0, depth);
+            numbering[depth - 1]++;
+        }
+        tocItem.numbering = numbering;
+    }
+}
+const RemarkFlexibleToc = (options) => {
+    const settings = Object.assign({}, DEFAULT_SETTINGS, options);
+    const exludeRegexFilter = settings.exclude &&
+        (Array.isArray(settings.exclude)
+            ? new RegExp("^(" + settings.exclude.join("|") + ")$", "i")
+            : new RegExp("^(" + settings.exclude + ")$", "i"));
+    return (tree, file) => {
+        const slugger = new GithubSlugger();
+        const tocItems = [];
+        visit(tree, "heading", (_node, _index, _parent) => {
+            if (!_parent)
+                return;
+            const depth = _node.depth;
+            const value = toString(_node, { includeImageAlt: false });
+            const href = `#${settings.prefix ?? ""}${slugger.slug(value)}`;
+            const parent = _parent.type;
+            // maxDepth check
+            if (depth > settings.maxDepth)
+                return CONTINUE;
+            // skipLevels check
+            if (settings.skipLevels.includes(depth))
+                return CONTINUE;
+            // skipParents check
+            if (parent !== "root" && settings.skipParents.includes(parent))
+                return CONTINUE;
+            // exclude check
+            if (exludeRegexFilter && exludeRegexFilter.test(value))
+                return CONTINUE;
+            // Other remark plugins can store custom data in node.data.hProperties
+            // I omitted node.data.hName and node.data.hChildren since not related with toc
+            const data = _node.data?.hProperties
+                ? { ..._node.data.hProperties }
+                : undefined;
+            tocItems.push({
+                value,
+                href,
+                depth,
+                numbering: [],
+                parent,
+                ...(data && { data }),
+            });
+            return CONTINUE;
+        });
+        addNumbering(tocItems);
+        // it is allowed to modify the TOC in the callback
+        settings.callback?.(tocItems);
+        // method - 1 for exposing the data via vfile.data **************************
+        // other plugins are not allowed to mutate the exposed TOC
+        // The spreading is slower than push but need to fresh copy
+        file.data[settings.tocName] = [...tocItems];
+        // method - 2 for exposing the data via reference array *********************
+        if (options?.tocRef) {
+            // prevent dublication if the plugin is called more than once
+            settings.tocRef.length = 0;
+            tocItems.forEach((tocItem) => {
+                // the tocRef is not allowed to mutate the vfile.data.toc
+                settings.tocRef.push(tocItem);
+            });
+        }
+    };
+};
+export default RemarkFlexibleToc;
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "remark-flexible-toc",
+  "version": "1.0.0",
+  "description": "Remark plugin to expose the table of contents via Vfile.data or via an option reference",
+  "type": "module",
+  "exports": "./dist/esm/index.js",
+  "main": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "scripts": {
+    "prebuild": "rimraf dist",
+    "build": "npm run prebuild && tsc",
+    "lint": "eslint .",
+    "prettier": "prettier --write .",
+    "test": "vitest",
+    "test:ci": "vitest --watch=false",
+    "test:file": "vitest without_options.spec.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run test:ci && npm run prettier && npm run lint"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipikuka/remark-flexible-toc.git"
+  },
+  "keywords": [
+    "unified",
+    "mdast",
+    "remark",
+    "markdown",
+    "MDX",
+    "plugin",
+    "remark-plugin",
+    "TOC",
+    "table of contents",
+    "remark-toc",
+    "remark-flexible-toc"
+  ],
+  "author": "ipikuka <talatkuyuk@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ipikuka/remark-flexible-toc#readme",
+  "bugs": {
+    "url": "https://github.com/ipikuka/remark-flexible-toc/issues"
+  },
+  "devDependencies": {
+    "@types/dedent": "^0.7.2",
+    "@types/node": "^20.10.5",
+    "@typescript-eslint/eslint-plugin": "^6.16.0",
+    "@typescript-eslint/parser": "^6.16.0",
+    "dedent": "^0.7.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.2",
+    "prettier": "^3.1.1",
+    "rehype-format": "^5.0.0",
+    "rehype-stringify": "^10.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.0.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "unified": "^11.0.4",
+    "vitest": "^1.3.0"
+  },
+  "dependencies": {
+    "@types/mdast": "^4.0.0",
+    "github-slugger": "^2.0.0",
+    "mdast-util-to-string": "^4.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+import { type Plugin } from "unified";
+import { type Root, type HeadingData } from "mdast";
+import { visit, CONTINUE } from "unist-util-visit";
+import GithubSlugger from "github-slugger";
+import { toString } from "mdast-util-to-string";
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type PartiallyRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+export type HeadingParent =
+  | "root"
+  | "blockquote"
+  | "footnoteDefinition"
+  | "listItem"
+  | "container"
+  | "mdxJsxFlowElement";
+
+export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6;
+
+export type TocItem = {
+  value: string;
+  href: string;
+  depth: HeadingDepth;
+  numbering: number[];
+  parent: HeadingParent;
+  data?: Record<string, unknown>;
+};
+
+/**
+ * tocName (default: "toc") - the key name which is attached into vfile.data
+ * tocRef (default: []) — another way of exposing the tocItems
+ * maxDepth (default: 6) — max heading depth to include in the table of contents; this is inclusive: when set to 3, level three headings are included
+ * skipLevels (default: [1]) — disallowed heading levels, by default the article h1 is not expected to be in the TOC
+ * skipParents (default: []) — disallow headings to be children of certain node types, (the "root" can not be skipped)
+ * exclude — headings to skip, wrapped in new RegExp('^(' + value + ')$', 'i'); any heading matching this expression will not be present in the table of contents
+ * prefix - the text that will be attached to headings as prefix, like "text-prefix-"
+ * callback - It is a callback function to take the array of toc items as an argument
+ */
+export type FlexibleTocOptions = {
+  tocName?: string;
+  tocRef?: TocItem[];
+  maxDepth?: HeadingDepth;
+  skipLevels?: HeadingDepth[];
+  skipParents?: Exclude<HeadingParent, "root">[];
+  exclude?: string | string[];
+  prefix?: string;
+  callback?: (toc: TocItem[]) => undefined;
+};
+
+type PartiallyRequiredFlexibleTocOptions = Prettify<
+  PartiallyRequired<
+    FlexibleTocOptions,
+    "tocName" | "tocRef" | "maxDepth" | "skipLevels" | "skipParents"
+  >
+>;
+
+const DEFAULT_SETTINGS = {
+  tocName: "toc",
+  tocRef: [],
+  maxDepth: 6,
+  skipLevels: [1],
+  skipParents: [],
+};
+
+type ExtendedHeadingData = HeadingData & { hProperties: Record<string, unknown> };
+
+/**
+ * adds numberings to the TOC items.
+ * why "number[]"? It is because up to you joining with dot or dash or slicing the first number (reserved for h1)
+ *
+ * [1]
+ * [1,1]
+ * [1,2]
+ * [1,2,1]
+ */
+function addNumbering(arr: TocItem[]) {
+  for (let i = 0; i < arr.length; i++) {
+    const tocItem = arr[i];
+    const depth = tocItem.depth;
+
+    let numbering: number[] = [];
+
+    const prevObj = i > 0 ? arr[i - 1] : undefined;
+    const prevDepth = prevObj ? prevObj.depth : undefined;
+    const prevNumbering = prevObj ? prevObj.numbering : undefined;
+
+    if (!prevNumbering || !prevDepth) {
+      numbering = Array.from({ length: depth }, () => 1);
+    } else if (depth === prevDepth) {
+      numbering = [...prevNumbering];
+      numbering[depth - 1]++;
+    } else if (depth > prevDepth) {
+      numbering = [
+        ...prevNumbering,
+        ...(Array.from(
+          { length: depth - prevDepth }, // if depth is more bigger than prevDepth, put more "1" inside the array
+          () => 1,
+        ) as HeadingDepth[]),
+      ];
+    } else if (depth < prevDepth) {
+      numbering = prevNumbering.slice(0, depth);
+      numbering[depth - 1]++;
+    }
+
+    tocItem.numbering = numbering;
+  }
+}
+
+const RemarkFlexibleToc: Plugin<[FlexibleTocOptions?], Root> = (options) => {
+  const settings = Object.assign(
+    {},
+    DEFAULT_SETTINGS,
+    options,
+  ) as PartiallyRequiredFlexibleTocOptions;
+
+  const exludeRegexFilter =
+    settings.exclude &&
+    (Array.isArray(settings.exclude)
+      ? new RegExp("^(" + settings.exclude.join("|") + ")$", "i")
+      : new RegExp("^(" + settings.exclude + ")$", "i"));
+
+  return (tree, file) => {
+    const slugger = new GithubSlugger();
+    const tocItems: TocItem[] = [];
+
+    visit(tree, "heading", (_node, _index, _parent) => {
+      if (!_parent) return;
+
+      const depth = _node.depth;
+      const value = toString(_node, { includeImageAlt: false });
+      const href = `#${settings.prefix ?? ""}${slugger.slug(value)}`;
+      const parent = _parent.type;
+
+      // maxDepth check
+      if (depth > settings.maxDepth) return CONTINUE;
+
+      // skipLevels check
+      if (settings.skipLevels.includes(depth)) return CONTINUE;
+
+      // skipParents check
+      if (parent !== "root" && settings.skipParents.includes(parent)) return CONTINUE;
+
+      // exclude check
+      if (exludeRegexFilter && exludeRegexFilter.test(value)) return CONTINUE;
+
+      // Other remark plugins can store custom data in node.data.hProperties
+      // I omitted node.data.hName and node.data.hChildren since not related with toc
+      const data = (_node.data as ExtendedHeadingData)?.hProperties
+        ? { ...(_node.data as ExtendedHeadingData).hProperties }
+        : undefined;
+
+      tocItems.push({
+        value,
+        href,
+        depth,
+        numbering: [],
+        parent,
+        ...(data && { data }),
+      });
+
+      return CONTINUE;
+    });
+
+    addNumbering(tocItems);
+
+    // it is allowed to modify the TOC in the callback
+    settings.callback?.(tocItems);
+
+    // method - 1 for exposing the data via vfile.data **************************
+
+    // other plugins are not allowed to mutate the exposed TOC
+    // The spreading is slower than push but need to fresh copy
+    file.data[settings.tocName] = [...tocItems];
+
+    // method - 2 for exposing the data via reference array *********************
+
+    if (options?.tocRef) {
+      // prevent dublication if the plugin is called more than once
+      settings.tocRef.length = 0;
+
+      tocItems.forEach((tocItem) => {
+        // the tocRef is not allowed to mutate the vfile.data.toc
+        settings.tocRef.push(tocItem);
+      });
+    }
+  };
+};
+
+export default RemarkFlexibleToc;