@md-plugins/md-plugin-link 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,90 @@
+# @md-plugins/md-plugin-link
+
+A **Markdown-It** plugin that customizes the rendering of links in Markdown content. This plugin is especially useful for Vue.js applications, where internal links can be replaced with Vue Router components (e.g., `<router-link>`).
+
+## Features
+
+- Replaces standard `<a>` tags with a custom link tag (e.g., `MarkdownLink` or `router-link`) for internal links.
+- Adds a customizable attribute (e.g., `to`) for routing.
+- Automatically injects import statements for required components into the `pageScripts` property in the Markdown-It environment (`env`).
+- Retains external links as standard `<a>` tags.
+
+## Installation
+
+Install the plugin via your preferred package manager:
+
+```bash
+# With npm:
+npm install @md-plugins/md-plugin-link
+# Or with Yarn:
+yarn add @md-plugins/md-plugin-link
+# Or with pnpm:
+pnpm add @md-plugins/md-plugin-link
+```
+
+## Usage
+
+### Basic Setup
+
+```js
+import MarkdownIt from 'markdown-it';
+import { linkPlugin } from '@md-plugins/md-plugin-link';
+import type { MarkdownItEnv } from '@md-plugins/shared';
+
+const md = new MarkdownIt();
+md.use(linkPlugin, {
+  linkTag: 'MarkdownLink', // Custom link tag (e.g., Vue Router component)
+  linkToKeyword: 'to', // Attribute to use for internal links
+  pageScript: 'import MarkdownLink from "src/components/md/MarkdownLink.vue";',
+});
+
+const markdownContent = `
+[Internal Link](/internal-page)
+[External Link](https://example.com)
+`;
+
+const env: MarkdownItEnv = {};
+const renderedOutput = md.render(markdownContent, env);
+
+console.log('Rendered Output:', renderedOutput);
+console.log('Page Scripts:', Array.from(env.pageScripts || []));
+```
+
+### Example Output
+
+For the example above, the plugin produces the following output:
+
+```html
+<p>
+  <MarkdownLink to="/internal-page">Internal Link</MarkdownLink>
+  <a href="https://example.com">External Link</a>
+</p>
+```
+
+Additionally, the `pageScripts` property in the `env` object will contain:
+
+```js
+Set(['import MarkdownLink from "src/components/md/MarkdownLink.vue";']);
+```
+
+## Options
+
+The `md-plugin-link` plugin supports the following options:
+
+| Option        | Type   | Default                                                          | Description                                                     |
+| ------------- | ------ | ---------------------------------------------------------------- | --------------------------------------------------------------- |
+| linkTag       | string | 'MarkdownLink'                                                   | Custom tag to use for internal links.                           |
+| linkToKeyword | string | 'to'                                                             | Attribute to use for internal links (e.g., to for router-link). |
+| pageScript    | string | 'import MarkdownLink from "src/components/md/MarkdownLink.vue";' | Import statement for required components.                       |
+
+## Testing
+
+Run the tests 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,33 @@
+import { PluginWithOptions } from 'markdown-it';
+
+interface LinkPluginOptions {
+    /**
+     * The tag for the internal link
+     *
+     * @default 'MarkdownLink'
+     */
+    linkTag?: string;
+    /**
+     * The "to" keyword" for the internal link
+     *
+     * @default 'to'
+     */
+    linkToKeyword?: string;
+    /**
+     * add import statements to the page.
+     *
+     */
+    pageScript?: string;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included for tags.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const linkPlugin: PluginWithOptions<LinkPluginOptions>;
+
+export { type LinkPluginOptions, linkPlugin };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { PluginWithOptions } from 'markdown-it';
+
+interface LinkPluginOptions {
+    /**
+     * The tag for the internal link
+     *
+     * @default 'MarkdownLink'
+     */
+    linkTag?: string;
+    /**
+     * The "to" keyword" for the internal link
+     *
+     * @default 'to'
+     */
+    linkToKeyword?: string;
+    /**
+     * add import statements to the page.
+     *
+     */
+    pageScript?: string;
+}
+declare module '@md-plugins/shared' {
+    interface MarkdownItEnv {
+        /**
+         * An array of page script (import statements) to be included for tags.
+         */
+        pageScripts?: Set<string>;
+    }
+}
+
+declare const linkPlugin: PluginWithOptions<LinkPluginOptions>;
+
+export { type LinkPluginOptions, linkPlugin };

package/dist/index.mjs

@@ -0,0 +1,45 @@
+const linkPlugin = (md, {
+  linkTag = "MarkdownLink",
+  linkToKeyword = "to",
+  pageScript = 'import MarkdownLink from "src/components/md/MarkdownLink.vue"'
+} = {}) => {
+  md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    if (!token) {
+      return "";
+    }
+    const hrefIndex = token.attrIndex("href");
+    if (hrefIndex < 0 || !token.attrs) {
+      return self.renderToken(tokens, idx, options);
+    }
+    const link = token.attrs[hrefIndex];
+    const url = link[1];
+    token.tag = linkTag;
+    link[0] = linkToKeyword;
+    link[1] = decodeURI(url);
+    if (pageScript) {
+      if (!env.pageScripts) {
+        env.pageScripts = /* @__PURE__ */ new Set();
+      }
+      env.pageScripts.add(pageScript);
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+  md.renderer.rules.link_close = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    if (!token) {
+      return "";
+    }
+    let openIdx = idx - 1;
+    while (openIdx >= 0 && tokens[openIdx].type !== "link_open") {
+      openIdx--;
+    }
+    const openingToken = tokens[openIdx];
+    if (openingToken && openingToken.tag) {
+      token.tag = openingToken.tag;
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+};
+
+export { linkPlugin };

package/package.json

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