@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:

# with pnpm:
pnpm add @md-plugins/md-plugin-link
# with bun:
bun add @md-plugins/md-plugin-link
# with Yarn:
yarn add @md-plugins/md-plugin-link
# with npm:
npm install @md-plugins/md-plugin-link

Usage

Basic Setup

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 "@/.q-press/components/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:

<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:

Set(['import MarkdownLink from "@/.q-press/components/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 "@/.q-press/components/MarkdownLink.vue";' | Import statement for required components. |

Testing

Run the tests to ensure the plugin behaves as expected:

pnpm test

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

Support

If md-plugin-link is useful in your workflow and you want to support ongoing maintenance:

• GitHub Sponsors: https://github.com/sponsors/hawkeye64
• PayPal: https://paypal.me/hawkeye64

License

This project is licensed under the MIT License. See the LICENSE file for details.