@md-plugins/md-plugin-frontmatter 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,108 @@
+# @md-plugins/md-plugin-frontmatter
+
+A **Markdown-It** plugin that extracts and processes frontmatter from Markdown content. Frontmatter is commonly used for metadata such as titles, authors, and dates, making this plugin essential for static site generators, documentation tools, and content management systems.
+
+## Features
+
+- Extracts frontmatter from Markdown files.
+- Supports rendering the frontmatter as raw Markdown or HTML.
+- Compatible with various frontmatter syntaxes (YAML, JSON, TOML) via the `gray-matter` library.
+- Stores extracted frontmatter in the `frontmatter` property of the Markdown-It environment (`env`).
+- Optionally renders an excerpt from the Markdown content.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-frontmatter
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-frontmatter
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-frontmatter
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter';
+import type { MarkdownItEnv } from '@md-plugins/shared';
+
+const md = new MarkdownIt();
+md.use(frontmatterPlugin, {
+  renderExcerpt: true,
+});
+
+const markdownContent = `
+---
+title: Frontmatter Example
+author: Jane Doe
+date: 2024-01-01
+---
+
+# Main Content
+
+This is the main content of the Markdown file.
+`;
+
+const env: MarkdownItEnv = {};
+const renderedOutput = md.render(markdownContent, env);
+
+console.log('Rendered Output:', renderedOutput);
+console.log('Extracted Frontmatter:', env.frontmatter);
+console.log('Extracted Excerpt:', env.excerpt);
+```
+
+### Example Output
+
+For the example above, the `env` will contain:
+
+```json
+{
+  "frontmatter": {
+    "title": "Frontmatter Example",
+    "author": "Jane Doe",
+    "date": "2024-01-01"
+  },
+  "excerpt": "<p>This is the main content of the Markdown file.</p>"
+}
+```
+
+## Options
+
+The `md-plugin-frontmatter` plugin supports the following options:
+
+| Option            | Type    | Default | Description                                                                                    |
+| ----------------- | ------- | ------- | ---------------------------------------------------------------------------------------------- |
+| grayMatterOptions | object  | {}      | Options for the gray-matter library. Refer to the gray-matter documentation.                   |
+| renderExcerpt     | boolean | true    | Whether to render the excerpt as HTML. If false, the raw Markdown is extracted as the excerpt. |
+
+## Advanced Usage
+
+### Customizing Frontmatter Parsing
+
+You can customize the behavior of the `gray-matter` library by passing `grayMatterOptions`:
+
+```js
+md.use(frontmatterPlugin, {
+  grayMatterOptions: {
+    delimiters: '+++', // Use "+++" as the frontmatter delimiter
+  },
+});
+```
+
+## Testing
+
+Run the unit tests with `Vitest` to ensure the plugin behaves as expected:
+
+```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,49 @@
+import { PluginWithOptions } from 'markdown-it';
+import matter from 'gray-matter';
+
+type GrayMatterOptions = matter.GrayMatterOption<string, GrayMatterOptions>;
+/**
+ * Options of md-plugin-frontmatter
+ */
+interface FrontmatterPluginOptions {
+    /**
+     * Options of gray-matter
+     *
+     * @see https://github.com/jonschlinkert/gray-matter#options
+     */
+    grayMatterOptions?: GrayMatterOptions;
+    /**
+     * Render the excerpt or not
+     *
+     * @default true
+     */
+    renderExcerpt?: boolean;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * The raw Markdown content without frontmatter
+         */
+        content?: string;
+        /**
+         * The excerpt that extracted by `md-plugin-frontmatter`
+         *
+         * - Would be the rendered HTML when `renderExcerpt` is enabled
+         * - Would be the raw Markdown when `renderExcerpt` is disabled
+         */
+        excerpt?: string;
+        /**
+         * The frontmatter that extracted by `md-plugin-frontmatter`
+         */
+        frontmatter?: Record<string, unknown>;
+    }
+}
+
+/**
+ * Get markdown frontmatter and excerpt
+ *
+ * Extract them into env
+ */
+declare const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions>;
+
+export { type FrontmatterPluginOptions, frontmatterPlugin };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { PluginWithOptions } from 'markdown-it';
+import matter from 'gray-matter';
+
+type GrayMatterOptions = matter.GrayMatterOption<string, GrayMatterOptions>;
+/**
+ * Options of md-plugin-frontmatter
+ */
+interface FrontmatterPluginOptions {
+    /**
+     * Options of gray-matter
+     *
+     * @see https://github.com/jonschlinkert/gray-matter#options
+     */
+    grayMatterOptions?: GrayMatterOptions;
+    /**
+     * Render the excerpt or not
+     *
+     * @default true
+     */
+    renderExcerpt?: boolean;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * The raw Markdown content without frontmatter
+         */
+        content?: string;
+        /**
+         * The excerpt that extracted by `md-plugin-frontmatter`
+         *
+         * - Would be the rendered HTML when `renderExcerpt` is enabled
+         * - Would be the raw Markdown when `renderExcerpt` is disabled
+         */
+        excerpt?: string;
+        /**
+         * The frontmatter that extracted by `md-plugin-frontmatter`
+         */
+        frontmatter?: Record<string, unknown>;
+    }
+}
+
+/**
+ * Get markdown frontmatter and excerpt
+ *
+ * Extract them into env
+ */
+declare const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions>;
+
+export { type FrontmatterPluginOptions, frontmatterPlugin };

package/dist/index.mjs

@@ -0,0 +1,32 @@
+import grayMatter from 'gray-matter';
+
+const frontmatterPlugin = (md, { grayMatterOptions, renderExcerpt = true } = {}) => {
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    let data, content, excerpt;
+    try {
+      ({ data, content } = grayMatter(src, grayMatterOptions));
+    } catch (error) {
+      console.error("Failed to parse frontmatter:", error);
+      data = {};
+      content = src;
+      excerpt = void 0;
+    }
+    env.content = content;
+    env.frontmatter = {
+      // allow providing default value
+      ...env.frontmatter,
+      ...data
+    };
+    env.excerpt = renderExcerpt && data.excerpt ? (
+      // render the excerpt with original markdown-it render method.
+      render(data.excerpt, env)
+    ) : (
+      // use the raw excerpt directly
+      excerpt
+    );
+    return render(content, env);
+  };
+};
+
+export { frontmatterPlugin };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@md-plugins/md-plugin-frontmatter",
+  "version": "0.1.0-alpha.1",
+  "description": "A markdown-it plugin for handling frontmatter in markdown files.",
+  "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",
+    "gray-matter": "^4.0.3",
+    "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"
+  }
+}