@mdit-vue/plugin-frontmatter 0.5.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.5.0](https://github.com/mdit-vue/mdit-vue/compare/v0.4.0...v0.5.0) (2022-07-06)
+
+### Features
+
+- **plugin-frontmatter:** add frontmatter plugin ([bcffc7a](https://github.com/mdit-vue/mdit-vue/commit/bcffc7a7fef0c48a869d703f0358d168524ac19e))

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,66 @@
+# @mdit-vue/plugin-frontmatter
+
+[![npm](https://badgen.net/npm/v/@mdit-vue/plugin-frontmatter)](https://www.npmjs.com/package/@mdit-vue/plugin-frontmatter)
+[![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 frontmatter with [gray-matter](https://github.com/jonschlinkert/gray-matter).
+
+- Extract frontmatter into markdown-it `env.frontmatter`.
+- Allow providing default frontmatter via markdown-it `env.frontmatter`.
+- Support extracting rendered excerpt into markdown-it `env.excerpt`.
+
+## Install
+
+```sh
+npm i @mdit-vue/plugin-frontmatter
+```
+
+## Usage
+
+```ts
+import MarkdownIt from 'markdown-it';
+import { frontmatterPlugin } from '@mdit-vue/plugin-frontmatter';
+
+const md = MarkdownIt({ html: true }).use(frontmatterPlugin, {
+  // options
+  grayMatterOptions: {
+    excerpt: true,
+    excerpt_separator: '<!-- more -->',
+  },
+});
+const env: MarkdownItEnv = {};
+
+const rendered = md.render(
+  `\
+---
+title: foobar
+---
+Everything above <!-- more --> will be extracted as excerpt.
+<!-- more -->
+`,
+  env,
+);
+
+console.log(env.frontmatter);
+console.log(env.excerpt);
+```
+
+## Options
+
+### grayMatterOptions
+
+- Type: `GrayMatterOptions`
+
+- Details:
+
+  Options of [gray-matter](https://github.com/jonschlinkert/gray-matter).
+
+### renderExcerpt
+
+- Type: `boolean`
+
+- Default: `true`
+
+  Render the [excerpt](https://github.com/jonschlinkert/gray-matter#optionsexcerpt) with markdown-it or not.
+
+  This option will only take effects when `grayMatterOptions.excerpt` is enabled (disabled by default) or `grayMatterOptions.excerpt_separator` is set (undefined by default).

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,24 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const grayMatter = require('gray-matter');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e["default"] : e; }
+
+const grayMatter__default = /*#__PURE__*/_interopDefaultLegacy(grayMatter);
+
+const frontmatterPlugin = (md, { grayMatterOptions, renderExcerpt = true } = {}) => {
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    const { data, content, excerpt = "" } = grayMatter__default(src, grayMatterOptions);
+    env.frontmatter = {
+      ...env.frontmatter,
+      ...data
+    };
+    env.excerpt = renderExcerpt && excerpt ? render(excerpt, { ...env }) : excerpt;
+    return render(content, env);
+  };
+};
+
+exports.frontmatterPlugin = frontmatterPlugin;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { PluginWithOptions } from 'markdown-it';
+import { GrayMatterOption } from 'gray-matter';
+
+declare type GrayMatterOptions = GrayMatterOption<string, GrayMatterOptions>;
+/**
+ * Options of @mdit-vue/plugin-frontmatter
+ */
+interface FrontmatterPluginOptions {
+    /**
+     * Options of gray-matter
+     *
+     * @see https://github.com/jonschlinkert/gray-matter#options
+     */
+    grayMatterOptions?: GrayMatterOptions;
+    /**
+     * Render the excerpt or not
+     */
+    renderExcerpt?: boolean;
+}
+declare module '@mdit-vue/shared' {
+    interface MarkdownItEnv {
+        excerpt?: string;
+        frontmatter?: Record<string, unknown>;
+    }
+}
+
+/**
+ * Get markdown frontmatter and excerpt
+ *
+ * Extract them to env
+ */
+declare const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions>;
+
+export { FrontmatterPluginOptions, frontmatterPlugin };

package/dist/index.mjs

@@ -0,0 +1,16 @@
+import grayMatter from 'gray-matter';
+
+const frontmatterPlugin = (md, { grayMatterOptions, renderExcerpt = true } = {}) => {
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    const { data, content, excerpt = "" } = grayMatter(src, grayMatterOptions);
+    env.frontmatter = {
+      ...env.frontmatter,
+      ...data
+    };
+    env.excerpt = renderExcerpt && excerpt ? render(excerpt, { ...env }) : excerpt;
+    return render(content, env);
+  };
+};
+
+export { frontmatterPlugin };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mdit-vue/plugin-frontmatter",
+  "version": "0.5.0",
+  "description": "A markdown-it plugin to get markdown frontmatter",
+  "keywords": [
+    "markdown-it",
+    "markdown-it-plugin",
+    "vue",
+    "frontmatter",
+    "excerpt"
+  ],
+  "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.5.0",
+    "@types/markdown-it": "^12.2.3",
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^13.0.1"
+  },
+  "devDependencies": {
+    "c8": "^7.11.3",
+    "unbuild": "^0.7.4",
+    "vitest": "^0.17.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "33671b4a15611ea35b065269526449129eef99d6"
+}

package/src/frontmatter-plugin.ts

@@ -0,0 +1,38 @@
+import type { MarkdownItEnv } from '@mdit-vue/shared';
+import grayMatter from 'gray-matter';
+import type { PluginWithOptions } from 'markdown-it';
+import type { FrontmatterPluginOptions } from './types';
+
+/**
+ * Get markdown frontmatter and excerpt
+ *
+ * Extract them to env
+ */
+export const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions> = (
+  md,
+  { grayMatterOptions, renderExcerpt = true } = {},
+): void => {
+  const render = md.render.bind(md);
+  md.render = (src, env: MarkdownItEnv = {}) => {
+    const { data, content, excerpt = '' } = grayMatter(src, grayMatterOptions);
+
+    // extract frontmatter
+    env.frontmatter = {
+      // allow providing default value
+      ...env.frontmatter,
+      ...data,
+    };
+
+    // render and extract excerpt
+    env.excerpt =
+      renderExcerpt && excerpt
+        ? // render the excerpt with original markdown-it render method.
+          // here we spread `env` to avoid mutating the original object.
+          // using deep clone might be a safer choice.
+          render(excerpt, { ...env })
+        : // use the raw excerpt directly
+          excerpt;
+
+    return render(content, env);
+  };
+};

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,27 @@
+import type { GrayMatterOption } from 'gray-matter';
+
+type GrayMatterOptions = GrayMatterOption<string, GrayMatterOptions>;
+
+/**
+ * Options of @mdit-vue/plugin-frontmatter
+ */
+export interface FrontmatterPluginOptions {
+  /**
+   * Options of gray-matter
+   *
+   * @see https://github.com/jonschlinkert/gray-matter#options
+   */
+  grayMatterOptions?: GrayMatterOptions;
+
+  /**
+   * Render the excerpt or not
+   */
+  renderExcerpt?: boolean;
+}
+
+declare module '@mdit-vue/shared' {
+  interface MarkdownItEnv {
+    excerpt?: string;
+    frontmatter?: Record<string, unknown>;
+  }
+}

package/tests/frontmatter-plugin.spec.ts

@@ -0,0 +1,143 @@
+import type { MarkdownItEnv } from '@mdit-vue/shared';
+import MarkdownIt from 'markdown-it';
+import { describe, expect, it } from 'vitest';
+import { frontmatterPlugin } from '../src';
+import type { FrontmatterPluginOptions } from '../src';
+
+const testCases: {
+  source: string;
+  options: FrontmatterPluginOptions;
+  env: MarkdownItEnv;
+  frontmatter: MarkdownItEnv['frontmatter'];
+  excerpt: MarkdownItEnv['excerpt'];
+}[] = [
+  {
+    source: `\
+---
+str: string
+num: 123
+date: 2022-07-06
+---
+`,
+    options: {},
+    env: {},
+    frontmatter: {
+      str: 'string',
+      num: 123,
+      date: new Date('2022-07-06T00:00:00Z'),
+    },
+    excerpt: '',
+  },
+  {
+    source: `\
+---
+foo: foo
+bar: bar
+---
+`,
+    options: {},
+    env: {
+      frontmatter: {
+        foo: 'default-foo',
+        baz: 'default-baz',
+      },
+    },
+    frontmatter: {
+      foo: 'foo',
+      bar: 'bar',
+      baz: 'default-baz',
+    },
+    excerpt: '',
+  },
+  {
+    source: `\
+# Hello, world
+---
+`,
+    options: {},
+    env: {},
+    frontmatter: {},
+    excerpt: '',
+  },
+  {
+    source: `\
+---
+foo: foo
+bar: bar
+---
+# Hello, world
+---
+`,
+    options: {
+      grayMatterOptions: {
+        excerpt: true,
+      },
+      renderExcerpt: true,
+    },
+    env: {},
+    frontmatter: {
+      foo: 'foo',
+      bar: 'bar',
+    },
+    excerpt: '<h1>Hello, world</h1>\n',
+  },
+  {
+    source: `\
+---
+foo: foo
+bar: bar
+---
+# Hello, world
+<!-- more -->
+`,
+    options: {
+      grayMatterOptions: {
+        excerpt: true,
+        excerpt_separator: '<!-- more -->',
+      },
+      renderExcerpt: true,
+    },
+    env: {},
+    frontmatter: {
+      foo: 'foo',
+      bar: 'bar',
+    },
+    excerpt: '<h1>Hello, world</h1>\n',
+  },
+  {
+    source: `\
+---
+foo: foo
+bar: bar
+---
+# Hello, world
+<!-- more -->
+`,
+    options: {
+      grayMatterOptions: {
+        excerpt: true,
+        excerpt_separator: '<!-- more -->',
+      },
+      renderExcerpt: false,
+    },
+    env: {},
+    frontmatter: {
+      foo: 'foo',
+      bar: 'bar',
+    },
+    excerpt: '# Hello, world\n',
+  },
+];
+
+describe('@mdit-vue/plugin-frontmatter > frontmatter-plugin', () => {
+  testCases.forEach(
+    ({ source, options, env: rawEnv, frontmatter, excerpt }, i) =>
+      it(`case ${i}`, () => {
+        const md = MarkdownIt().use(frontmatterPlugin, options);
+        const env: MarkdownItEnv = { ...rawEnv };
+        md.render(source, env);
+        expect(env.frontmatter).toEqual(frontmatter);
+        expect(env.excerpt).toEqual(excerpt);
+      }),
+  );
+});