@md-plugins/md-plugin-imports 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,127 @@
+# @md-plugins/md-plugin-imports
+
+A **Markdown-It** plugin that extracts and stores `<script import>` blocks from Markdown content. This is useful for managing page-level imports in environments where Markdown is rendered dynamically, such as in Vue.js applications.
+
+The imports are stored in the `pageScripts` property of the Markdown-It environment (`env`). During post-processing the array if imports (Set) can be used to inject the required scripts into the Vue SFC.
+
+## Features
+
+- Extracts `<script import>` blocks from Markdown content.
+- Stores the extracted imports in the `pageScripts` property of the Markdown-It environment (`env`).
+- Cleans the `<script import>` blocks from the rendered output, leaving the rest of the Markdown intact.
+- Handles multiple `<script import>` blocks gracefully.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-imports
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-imports
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-imports
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { importsPlugin } from '@md-plugins/md-plugin-imports';
+import type { MarkdownItEnv } from '@md-plugins/shared';
+
+const md = new MarkdownIt();
+md.use(importsPlugin);
+
+const markdownContent = `
+<script import>
+import A from './A.vue';
+import B from './B.vue';
+</script>
+
+# Header
+
+Some content here.
+`;
+
+const env: MarkdownItEnv = {};
+const renderedOutput = md.render(markdownContent, env);
+
+console.log('Rendered Output:', renderedOutput);
+console.log('Page Scripts:', env.pageScripts);
+```
+
+### Options
+
+The `md-plugin-imports` plugin does not currently accept options. All `<script import>` blocks are processed by default.
+
+### Script Block Syntax
+
+The plugin recognizes `<script import>` blocks in the following format:
+
+```markdown
+<script import>
+import A from './A.vue';
+import B from './B.vue';
+</script>
+```
+
+### Notes
+
+- Script blocks should start with `<script import>` and end with `</script>`.
+- The plugin trims and parses the contents of the block line-by-line.
+
+## Advanced Usage
+
+### Multiple Script Blocks
+
+The plugin supports multiple `<script import>` blocks in a single Markdown file:
+
+```markdown
+<script import>
+import A from './A.vue';
+</script>
+
+# Header
+
+<script import>
+import B from './B.vue';
+</script>
+```
+
+Both `import A from './A.vue';` and `import B from './B.vue';` will be added to the pageScripts set. Internally, a `Set` is used to ensure uniqueness.
+
+## Frontmatter Compatibility
+
+The plugin does not interfere with frontmatter or other Markdown content:
+
+```markdown
+---
+title: Frontmatter Example
+---
+
+<script import>
+import C from './C.vue';
+</script>
+
+# Header
+
+Some content here.
+```
+
+The plugin processes the `<script import>` block while leaving the frontmatter intact.
+
+## Testing
+
+Run the unit tests with `Vitest`:
+
+```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,22 @@
+import { PluginSimple } from 'markdown-it';
+
+/**
+ * A Markdown-It plugin that extracts and stores script imports from the Markdown content.
+ *
+ * This plugin replaces script import blocks (delimited by `<script import>` and `</script>`) with an empty string,
+ * and adds the extracted script content to the `env.pageScripts` set in the Markdown-It environment.
+ *
+ * @param md - The Markdown-It instance to extend.
+ */
+declare const importsPlugin: PluginSimple;
+
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+export { importsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { PluginSimple } from 'markdown-it';
+
+/**
+ * A Markdown-It plugin that extracts and stores script imports from the Markdown content.
+ *
+ * This plugin replaces script import blocks (delimited by `<script import>` and `</script>`) with an empty string,
+ * and adds the extracted script content to the `env.pageScripts` set in the Markdown-It environment.
+ *
+ * @param md - The Markdown-It instance to extend.
+ */
+declare const importsPlugin: PluginSimple;
+
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+export { importsPlugin };

package/dist/index.mjs

@@ -0,0 +1,19 @@
+const scriptRE = /^\s*<script import>\n([\s\S]*?)\n\s*<\/script>/gm;
+const importsPlugin = (md) => {
+  const render = md.render.bind(md);
+  md.render = (src, env = {}) => {
+    if (!env.pageScripts) {
+      env.pageScripts = /* @__PURE__ */ new Set();
+    }
+    const mdContent = src.replace(scriptRE, (_, scriptContent) => {
+      const imports = scriptContent.split("\n").map((line) => line.trim()).filter(Boolean);
+      imports.forEach((importLine) => {
+        env.pageScripts.add(importLine);
+      });
+      return "";
+    });
+    return render(mdContent, env);
+  };
+};
+
+export { importsPlugin };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@md-plugins/md-plugin-imports",
+  "version": "0.1.0-alpha.1",
+  "description": "A markdown-it plugin for handling imports 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",
+    "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"
+  }
+}