@md-plugins/md-plugin-headers 0.1.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, Jeff Galbraith
+
+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,155 @@
+# @md-plugins/md-plugin-headers
+
+A **Markdown-It** plugin that extracts and processes headers from Markdown content. This plugin is ideal for generating Table of Contents (ToC) or managing headers for documentation and static sites.
+
+**NOTE:** When using with `vue-router` be sure to use `history` mode and not `hash` mode otherwise your hash links will not work as expected.
+
+## Features
+
+- Extracts headers based on specified levels (e.g., `h1`, `h2`, `h3`).
+- Supports custom slugification for header IDs.
+- Allows custom formatting for header titles.
+- Provides nested structure for headers (e.g., hierarchical ToC generation).
+- Compatible with Markdown-It environments for additional flexibility.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-headers
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-headers
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-headers
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { headersPlugin } from '@md-plugins/md-plugin-headers';
+import type { MarkdownItEnv } from '@md-plugins/shared';
+
+const md = new MarkdownIt();
+md.use(headersPlugin, {
+  level: [1, 2, 3], // Extract h1, h2, and h3 headers
+  slugify: (str) => str.toLowerCase().replace(/\s+/g, '-'),
+  format: (title) => title.toUpperCase(),
+});
+
+const markdownContent = `
+# Header 1
+
+## Subheader 1.1
+
+### Subheader 1.1.1
+`;
+
+const env: MarkdownItEnv = {};
+const renderedOutput = md.render(markdownContent, env);
+
+console.log('Rendered Output:', renderedOutput);
+console.log('Extracted Headers:', env.toc);
+```
+
+### Example Output
+
+The plugin processes headers and stores them in the `toc` property of the Markdown-It environment (`env`):
+
+```json
+[
+  {
+    "level": 1,
+    "title": "HEADER 1",
+    "id": "header-1",
+    "link": "#header-1",
+    "children": [
+      {
+        "level": 2,
+        "title": "SUBHEADER 1.1",
+        "id": "subheader-1-1",
+        "link": "#subheader-1-1",
+        "children": [
+          {
+            "level": 3,
+            "title": "SUBHEADER 1.1.1",
+            "id": "subheader-1-1-1",
+            "link": "#subheader-1-1-1",
+            "children": []
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+## Options
+
+The `md-plugin-headers` plugin supports the following options:
+
+| Option            | Type     | Default      | Description                                                          |
+| ----------------- | -------- | ------------ | -------------------------------------------------------------------- |
+| level             | number[] | [2, 3]       | Heading levels to extract (e.g., [2, 3] for h2, h3).                 |
+| slugify           | function | (str) => str | Function to generate slugs for header IDs.                           |
+| format            | function | (str) => str | Function to format header titles.                                    |
+| shouldAllowNested | boolean  | false        | Whether to allow headers inside nested blocks (e.g., lists, quotes). |
+
+## Advanced Usage
+
+### Generating a Table of Contents (ToC)
+
+With the `toc` property in `env`, you can build a ToC dynamically:
+
+```js
+function generateToC(toc) {
+  const list = toc
+    .map((item) => {
+      const children = item.children
+        ? `<ul>${generateToC(item.children)}</ul>`
+        : '';
+      return `<li><a href="${item.link}">${item.title}</a>${children}</li>`;
+    })
+    .join('');
+  return `<ul>${list}</ul>`;
+}
+
+const tocHtml = generateToC(env.toc);
+console.log('Generated ToC:', tocHtml);
+```
+
+### Custom Slugify Function
+
+You can use your own slugification logic for header IDs:
+
+```js
+md.use(headersPlugin, {
+  slugify: (str) => encodeURIComponent(str.replace(/\s+/g, '_')),
+});
+```
+
+Whatever you use on the backend, should be the same logic on the frontend for slugification so that they match when using hash links.
+
+### Nested Headers
+
+Enable nested headers to include headers inside blockquotes or lists:
+
+```js
+md.use(headersPlugin, {
+  shouldAllowNested: true,
+});
+```
+
+## Testing
+
+```bash
+pnpm test
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+import { PluginWithOptions } from 'markdown-it';
+
+/**
+ * Options of md-plugin-headers
+ */
+interface HeadersPluginOptions {
+    /**
+     * A custom slugification function
+     *
+     * Should use the same slugify function with markdown-it-anchor
+     * to ensure the link is matched
+     */
+    slugify?: (str: string) => string;
+    /**
+     * A function for formatting header title
+     */
+    format?: (str: string) => string;
+    /**
+     * Heading level that going to be extracted
+     *
+     * Should be a subset of markdown-it-anchor's `level` option
+     * to ensure the slug is existed
+     *
+     * @default [2,3]
+     */
+    level?: number[];
+    /**
+     * Should allow headers inside nested blocks or not
+     *
+     * If set to `true`, headers inside blockquote, list, etc. would also be extracted.
+     *
+     * @default false
+     */
+    shouldAllowNested?: boolean;
+}
+interface TocItem {
+    id: string;
+    title: string;
+    sub?: boolean;
+    deep?: boolean;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * The toc that are extracted by `md-plugin-headers`
+         */
+        toc?: TocItem[];
+    }
+}
+
+declare const headersPlugin: PluginWithOptions<HeadersPluginOptions>;
+
+export { type HeadersPluginOptions, type TocItem, headersPlugin };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { PluginWithOptions } from 'markdown-it';
+
+/**
+ * Options of md-plugin-headers
+ */
+interface HeadersPluginOptions {
+    /**
+     * A custom slugification function
+     *
+     * Should use the same slugify function with markdown-it-anchor
+     * to ensure the link is matched
+     */
+    slugify?: (str: string) => string;
+    /**
+     * A function for formatting header title
+     */
+    format?: (str: string) => string;
+    /**
+     * Heading level that going to be extracted
+     *
+     * Should be a subset of markdown-it-anchor's `level` option
+     * to ensure the slug is existed
+     *
+     * @default [2,3]
+     */
+    level?: number[];
+    /**
+     * Should allow headers inside nested blocks or not
+     *
+     * If set to `true`, headers inside blockquote, list, etc. would also be extracted.
+     *
+     * @default false
+     */
+    shouldAllowNested?: boolean;
+}
+interface TocItem {
+    id: string;
+    title: string;
+    sub?: boolean;
+    deep?: boolean;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * The toc that are extracted by `md-plugin-headers`
+         */
+        toc?: TocItem[];
+    }
+}
+
+declare const headersPlugin: PluginWithOptions<HeadersPluginOptions>;
+
+export { type HeadersPluginOptions, type TocItem, headersPlugin };

package/dist/index.mjs

@@ -0,0 +1,77 @@
+import { slugify } from '@md-plugins/shared';
+
+const titleRE = /<\/?[^>]+(>|$)/g;
+const apiRE = /^<MarkdownApi /;
+const apiNameRE = /(?:file|name)="([^"]+)"/;
+const installationRE = /^<MarkdownInstallation(?:\s+title="([^"]*)")?\s*/;
+const exampleRE = /^<MarkdownExample(?:\s+title="([^"]*)")?\s*/;
+function parseContent(str, slugify$1 = slugify, format = (_str) => _str) {
+  const title = String(str).replace(titleRE, "").trim();
+  return {
+    id: slugify$1(title),
+    title: format(title) ?? title
+  };
+}
+const headersPlugin = (md, {
+  level = [2, 3],
+  slugify: slugify$1 = slugify,
+  format
+} = {}) => {
+  const originalHeadingOpen = md.renderer.rules.heading_open;
+  const originalHtmlBlock = md.renderer.rules.html_block;
+  md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    if (!token) {
+      return self.renderToken(tokens, idx, options);
+    }
+    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+    const contentToken = tokens[idx + 1];
+    const content = contentToken && contentToken.children ? contentToken.children.reduce((acc, t) => acc + t.content, "") : "";
+    const { id, title } = parseContent(content, slugify$1, format);
+    token.attrSet("id", id);
+    token.attrSet("class", `markdown-heading markdown-${token.tag}`);
+    token.attrSet("@click", `copyHeading(\`${id}\`)`);
+    env.toc = env.toc || [];
+    if (level.includes(headerLevel)) {
+      if (headerLevel === level[0]) {
+        env.toc.push({ id, title });
+      } else {
+        env.toc.push({ id, title, sub: true });
+      }
+    }
+    if (typeof originalHeadingOpen === "function") {
+      return originalHeadingOpen(tokens, idx, options, env, self);
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+  md.renderer.rules.html_block = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    if (!token) {
+      return "";
+    }
+    env.toc = env.toc || [];
+    if (apiRE.test(token.content)) {
+      const match2 = apiNameRE.exec(token.content);
+      if (match2 !== null) {
+        const title = `${match2[1]} API`;
+        env.toc.push({ id: slugify$1(title), title, deep: true });
+      }
+    }
+    let match = token.content.match(installationRE);
+    if (match !== null) {
+      const title = match[1] ?? "Installation";
+      env.toc.push({ id: slugify$1(title), title, deep: true });
+    }
+    match = token.content.match(exampleRE);
+    if (match !== null) {
+      const title = match[1] ?? "Example";
+      env.toc.push({ id: slugify$1(title), title, deep: true });
+    }
+    if (typeof originalHtmlBlock === "function") {
+      return originalHtmlBlock(tokens, idx, options, env, self);
+    }
+    return token.content;
+  };
+};
+
+export { headersPlugin };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@md-plugins/md-plugin-headers",
+  "version": "0.1.0-alpha.1",
+  "description": "A markdown-it plugin for handling headers (H1-H6).",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "vue",
+    "types"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "markdown-it": "^14.1.0",
+    "@md-plugins/shared": "0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist",
+    "test": "vitest"
+  }
+}