@mdit-vue/plugin-headers 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.4.0](https://github.com/mdit-vue/mdit-vue/compare/v0.3.1...v0.4.0) (2022-07-02)
+
+### Features
+
+- **plugin-headers:** add headers plugin ([636aa9b](https://github.com/mdit-vue/mdit-vue/commit/636aa9be80051922ee290d61a5074f7d90d7b793))

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-present, mdit-vue Contributors
+
+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,73 @@
+# @mdit-vue/plugin-headers
+
+[![npm](https://badgen.net/npm/v/@mdit-vue/plugin-headers)](https://www.npmjs.com/package/@mdit-vue/plugin-headers)
+[![license](https://badgen.net/github/license/mdit-vue/mdit-vue)](https://github.com/mdit-vue/mdit-vue/blob/main/LICENSE)
+
+A [markdown-it](https://github.com/markdown-it/markdown-it) plugin to get markdown headers.
+
+- Extract all headers info into markdown-it `env.headers`.
+
+## Install
+
+```sh
+npm i @mdit-vue/plugin-headers
+```
+
+## Usage
+
+```ts
+import MarkdownIt from 'markdown-it';
+import { headersPlugin } from '@mdit-vue/plugin-headers';
+
+const md = MarkdownIt({ html: true }).use(headersPlugin, {
+  // options
+});
+const env: MarkdownItEnv = {};
+
+const rendered = md.render(
+  `\
+# h1
+## h2
+### h3
+`,
+  env,
+);
+
+console.log(env.headers);
+```
+
+## Options
+
+### format
+
+- Type: `(str: string) => string`
+
+- Details:
+
+  A function for formatting header title.
+
+### level
+
+- Type: `number[]`
+
+- Default: `[2, 3]`
+
+- Details:
+
+  Heading level that going to be extracted.
+
+  When using this plugin with [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) (recommended), this option should be a subset of markdown-it-anchor's `level` option to ensure the header slugs are existed.
+
+### slugify
+
+- Type: `(str: string) => string`
+
+- Default: `slugify` from `@mdit-vue/shared`
+
+- Details:
+
+  A custom slugification function.
+
+  The default slugify function comes from [@mdit-vue/shared](https://github.com/mdit-vue/mdit-vue/tree/main/packages/shared) package.
+
+  When using this plugin with [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) (recommended), this option will be ignored because the `id` of the headings have already been determined by markdown-it-anchor's `slugify` option.

package/build.config.ts

@@ -0,0 +1,11 @@
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+  clean: true,
+  declaration: true,
+  entries: ['src/index'],
+  rollup: {
+    emitCJS: true,
+    inlineDependencies: false,
+  },
+});

package/dist/index.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const shared = require('@mdit-vue/shared');
+
+const headersPlugin = (md, { level = [2, 3], slugify = shared.slugify, format } = {}) => {
+  let headers;
+  md.core.ruler.push("resolveHeaders", (state) => {
+    headers = shared.resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: false,
+      shouldEscapeText: false,
+      slugify,
+      format
+    });
+    return true;
+  });
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    const result = render(src, env);
+    env.headers = headers;
+    return result;
+  };
+};
+
+exports.headersPlugin = headersPlugin;

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { PluginWithOptions } from 'markdown-it';
+import { MarkdownItHeader } from '@mdit-vue/shared';
+export { MarkdownItHeader } from '@mdit-vue/shared';
+
+/**
+ * Options of @mdit-vue/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[];
+}
+declare module '@mdit-vue/shared' {
+    interface MarkdownItEnv {
+        headers?: MarkdownItHeader[];
+    }
+}
+
+/**
+ * Get markdown headers info
+ *
+ * Extract them to env
+ */
+declare const headersPlugin: PluginWithOptions<HeadersPluginOptions>;
+
+export { HeadersPluginOptions, headersPlugin };

package/dist/index.mjs

@@ -0,0 +1,23 @@
+import { resolveHeadersFromTokens, slugify } from '@mdit-vue/shared';
+
+const headersPlugin = (md, { level = [2, 3], slugify: slugify$1 = slugify, format } = {}) => {
+  let headers;
+  md.core.ruler.push("resolveHeaders", (state) => {
+    headers = resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: false,
+      shouldEscapeText: false,
+      slugify: slugify$1,
+      format
+    });
+    return true;
+  });
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    const result = render(src, env);
+    env.headers = headers;
+    return result;
+  };
+};
+
+export { headersPlugin };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mdit-vue/plugin-headers",
+  "version": "0.4.0",
+  "description": "A markdown-it plugin to get markdown headers",
+  "keywords": [
+    "markdown-it",
+    "markdown-it-plugin",
+    "vue",
+    "header",
+    "heading"
+  ],
+  "homepage": "https://github.com/mdit-vue",
+  "bugs": {
+    "url": "https://github.com/mdit-vue/mdit-vue/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdit-vue/mdit-vue.git"
+  },
+  "license": "MIT",
+  "author": "meteorlxy <meteor.lxy@foxmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@mdit-vue/shared": "0.4.0",
+    "@types/markdown-it": "^12.2.3",
+    "markdown-it": "^13.0.1"
+  },
+  "devDependencies": {
+    "c8": "^7.11.3",
+    "markdown-it-anchor": "^8.6.4",
+    "unbuild": "^0.7.4",
+    "vitest": "^0.16.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "744887e6f4733af8da2045625e72a476947cfc25"
+}

package/src/headers-plugin.ts

@@ -0,0 +1,40 @@
+import {
+  slugify as defaultSlugify,
+  resolveHeadersFromTokens,
+} from '@mdit-vue/shared';
+import type { MarkdownItEnv, MarkdownItHeader } from '@mdit-vue/shared';
+import type { PluginWithOptions } from 'markdown-it';
+import type { HeadersPluginOptions } from './types';
+
+/**
+ * Get markdown headers info
+ *
+ * Extract them to env
+ */
+export const headersPlugin: PluginWithOptions<HeadersPluginOptions> = (
+  md,
+  { level = [2, 3], slugify = defaultSlugify, format } = {},
+): void => {
+  let headers: MarkdownItHeader[];
+
+  // push the rule to the end of the chain
+  // resolve headers from the parsed tokens
+  md.core.ruler.push('resolveHeaders', (state) => {
+    headers = resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: false,
+      shouldEscapeText: false,
+      slugify,
+      format,
+    });
+    return true;
+  });
+
+  // extract headers to env
+  const render = md.render.bind(md);
+  md.render = (src, env: MarkdownItEnv = {}) => {
+    const result = render(src, env);
+    env.headers = headers;
+    return result;
+  };
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './headers-plugin';
+export * from './types';

package/src/types.ts

@@ -0,0 +1,37 @@
+import type { MarkdownItHeader } from '@mdit-vue/shared';
+
+export type { MarkdownItHeader };
+
+/**
+ * Options of @mdit-vue/plugin-headers
+ */
+export 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[];
+}
+
+declare module '@mdit-vue/shared' {
+  interface MarkdownItEnv {
+    headers?: MarkdownItHeader[];
+  }
+}

package/tests/__snapshots__/headers-plugin.spec.ts.snap

@@ -0,0 +1,223 @@
+// Vitest Snapshot v1
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers (h1, h2, h3, h4) > complexTree 1`] = `
+[
+  {
+    "children": [
+      {
+        "children": [
+          {
+            "children": [
+              {
+                "children": [],
+                "level": 4,
+                "slug": "s1-1-1-1",
+                "title": "s1-1-1-1",
+              },
+            ],
+            "level": 3,
+            "slug": "s1-1-1",
+            "title": "s1-1-1",
+          },
+          {
+            "children": [],
+            "level": 3,
+            "slug": "s1-1-2",
+            "title": "s1-1-2",
+          },
+          {
+            "children": [
+              {
+                "children": [],
+                "level": 4,
+                "slug": "s1-1-3-1",
+                "title": "s1-1-3-1",
+              },
+            ],
+            "level": 3,
+            "slug": "s1-1-3",
+            "title": "s1-1-3",
+          },
+        ],
+        "level": 2,
+        "slug": "s1-1",
+        "title": "s1-1",
+      },
+      {
+        "children": [],
+        "level": 2,
+        "slug": "s1-2",
+        "title": "s1-2",
+      },
+      {
+        "children": [
+          {
+            "children": [
+              {
+                "children": [],
+                "level": 4,
+                "slug": "s1-3-2-1",
+                "title": "s1-3-2-1",
+              },
+            ],
+            "level": 3,
+            "slug": "s1-3-2",
+            "title": "s1-3-2",
+          },
+        ],
+        "level": 2,
+        "slug": "s1-3",
+        "title": "s1-3",
+      },
+    ],
+    "level": 1,
+    "slug": "s1",
+    "title": "s1",
+  },
+]
+`;
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers (h1, h2, h3, h4) > reversedTree 1`] = `
+[
+  {
+    "children": [],
+    "level": 4,
+    "slug": "h4",
+    "title": "h4",
+  },
+  {
+    "children": [],
+    "level": 3,
+    "slug": "h3",
+    "title": "h3",
+  },
+  {
+    "children": [],
+    "level": 2,
+    "slug": "h2",
+    "title": "h2",
+  },
+  {
+    "children": [],
+    "level": 1,
+    "slug": "h1",
+    "title": "h1",
+  },
+]
+`;
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers (h1, h2, h3, h4) > simpleTree 1`] = `
+[
+  {
+    "children": [
+      {
+        "children": [
+          {
+            "children": [
+              {
+                "children": [],
+                "level": 4,
+                "slug": "h4",
+                "title": "h4",
+              },
+            ],
+            "level": 3,
+            "slug": "h3",
+            "title": "h3",
+          },
+        ],
+        "level": 2,
+        "slug": "h2",
+        "title": "h2",
+      },
+    ],
+    "level": 1,
+    "slug": "h1",
+    "title": "h1",
+  },
+]
+`;
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers with default option (h2, h3) > complexTree 1`] = `
+[
+  {
+    "children": [
+      {
+        "children": [],
+        "level": 3,
+        "slug": "s1-1-1",
+        "title": "s1-1-1",
+      },
+      {
+        "children": [],
+        "level": 3,
+        "slug": "s1-1-2",
+        "title": "s1-1-2",
+      },
+      {
+        "children": [],
+        "level": 3,
+        "slug": "s1-1-3",
+        "title": "s1-1-3",
+      },
+    ],
+    "level": 2,
+    "slug": "s1-1",
+    "title": "s1-1",
+  },
+  {
+    "children": [],
+    "level": 2,
+    "slug": "s1-2",
+    "title": "s1-2",
+  },
+  {
+    "children": [
+      {
+        "children": [],
+        "level": 3,
+        "slug": "s1-3-2",
+        "title": "s1-3-2",
+      },
+    ],
+    "level": 2,
+    "slug": "s1-3",
+    "title": "s1-3",
+  },
+]
+`;
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers with default option (h2, h3) > reversedTree 1`] = `
+[
+  {
+    "children": [],
+    "level": 3,
+    "slug": "h3",
+    "title": "h3",
+  },
+  {
+    "children": [],
+    "level": 2,
+    "slug": "h2",
+    "title": "h2",
+  },
+]
+`;
+
+exports[`@mdit-vue/plugin-headers > headers-plugin > should extract headers with default option (h2, h3) > simpleTree 1`] = `
+[
+  {
+    "children": [
+      {
+        "children": [],
+        "level": 3,
+        "slug": "h3",
+        "title": "h3",
+      },
+    ],
+    "level": 2,
+    "slug": "h2",
+    "title": "h2",
+  },
+]
+`;

package/tests/headers-plugin.spec.ts

@@ -0,0 +1,149 @@
+import { slugify } from '@mdit-vue/shared';
+import type { MarkdownItEnv, MarkdownItHeader } from '@mdit-vue/shared';
+import MarkdownIt from 'markdown-it';
+import anchorPlugin from 'markdown-it-anchor';
+import { describe, expect, it } from 'vitest';
+import { headersPlugin } from '../src';
+
+const fixtures = {
+  simpleTree: `\
+# h1
+## h2
+### h3
+#### h4
+##### h5
+###### h6
+`,
+  complexTree: `\
+# s1
+## s1-1
+### s1-1-1
+#### s1-1-1-1
+### s1-1-2
+### s1-1-3
+#### s1-1-3-1
+## s1-2
+## s1-3
+### s1-3-2
+#### s1-3-2-1
+##### s1-3-2-1-1
+##### s1-3-2-1-2
+`,
+  reversedTree: `\
+###### h6
+##### h5
+#### h4
+### h3
+## h2
+# h1
+`,
+};
+
+describe('@mdit-vue/plugin-headers > headers-plugin', () => {
+  describe('should extract headers with default option (h2, h3)', () => {
+    const md = MarkdownIt().use(headersPlugin);
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const env: MarkdownItEnv = {};
+        md.render(source, env);
+        expect(env.headers).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should extract nothing', () => {
+    const md = MarkdownIt().use(headersPlugin, {
+      level: [],
+    });
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const env: MarkdownItEnv = {};
+        md.render(source, env);
+        expect(env.headers).toEqual([]);
+      });
+    });
+  });
+
+  describe('should extract headers (h1, h2, h3, h4)', () => {
+    const md = MarkdownIt().use(headersPlugin, {
+      level: [1, 2, 3, 4],
+    });
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const env: MarkdownItEnv = {};
+        md.render(source, env);
+        expect(env.headers).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should not include html elements and should not escape texts', () => {
+    const md = MarkdownIt({
+      html: true,
+    })
+      .use(anchorPlugin, { slugify })
+      .use(headersPlugin, { slugify });
+
+    const testCases: [string, MarkdownItHeader[]][] = [
+      // html element should be ignored
+      [
+        '## foo <bar />',
+        [
+          {
+            level: 2,
+            title: 'foo',
+            slug: 'foo',
+            children: [],
+          },
+        ],
+      ],
+      // inline code should not be escaped
+      [
+        '## foo <bar/> `<code />`',
+        [
+          {
+            level: 2,
+            title: 'foo  <code />',
+            slug: 'foo-code',
+            children: [],
+          },
+        ],
+      ],
+      // text should not be escaped
+      [
+        '## foo <bar/> "baz"',
+        [
+          {
+            level: 2,
+            title: 'foo  "baz"',
+            slug: 'foo-baz',
+            children: [],
+          },
+        ],
+      ],
+      // text should not be escaped
+      [
+        '## < test >',
+        [
+          {
+            level: 2,
+            title: '< test >',
+            slug: 'test',
+            children: [],
+          },
+        ],
+      ],
+    ];
+
+    testCases.forEach(([source, expected], i) =>
+      it(`case ${i}`, () => {
+        const env: MarkdownItEnv = {};
+        md.render(source, env);
+        expect(env.headers).toEqual(expected);
+      }),
+    );
+  });
+});