Getting Started

Overview

This is a unified (remark) plugin to turn {text} syntax into links, optionally with an icon.

When Should I Use This?

This plugin is useful when you have a set of links that you want to quickly adopt them by a simple {text} syntax instead of writing [text](url) everytime in markdown, with a consistent styling and optionally with an icon.

It gives back a well-structured accessible HTML output, which can be styled by classname or used by JavaScript, for example to add some tooltips or other interactive features.

Installation

This package is ESM only.

It requires Node.js v16+.

npm

npm install remark-magic-link

yarn

yarn add remark-magic-link

pnpm

pnpm add remark-magic-link

bun

bun add remark-magic-link

esm.sh

import remarkMagicLink from 'https://esm.sh/remark-magic-link'

Usage

Say we have the following markdown file example.md:

# Title

{Vitest} dummy {Vue}

{Unified}

Paragraph

and a module example.js or example.ts:

example.js

import { remark } from 'remark'
import remarkMagicLink from 'remark-magic-link'
import { read } from 'to-vfile'

const options = {
  linksMap: {
    Vitest: 'https://github.com/vitest-dev/vitest',
    Vue: {
      link: 'https://github.com/vuejs/core',
      icon: 'https://vuejs.org/logo.svg',
    },
    Unified: {
      link: 'https://github.com/unifiedjs/unified',
      icon: false,
    }
  }
}

const file = await remark()
  .use(remarkMagicLink, options)
  .process(await read(new URL('example.md', import.meta.url)))

console.log(file.toString())

example.ts

import type { RemarkMagicLinkOptions } from 'remark-magic-link'
import { remark } from 'remark'
import remarkMagicLink from 'remark-magic-link'
import { read } from 'to-vfile'

const options: RemarkMagicLinkOptions = {
  linksMap: {
    Vitest: 'https://github.com/vitest-dev/vitest',
    Vue: {
      link: 'https://github.com/vuejs/core',
      icon: 'https://vuejs.org/logo.svg',
    },
    Unified: {
      link: 'https://github.com/unifiedjs/unified',
      icon: false,
    }
  }
}

const file = await remark()
  .use(remarkMagicLink, options)
  .process(await read(new URL('example.md', import.meta.url)))

console.log(file.toString())

Running node example.js or tsx example.ts yields:

formatted & decoded

# Title

<a class="remark-magic-link remark-magic-link-link remark-magic-link-with-icon" href="https://github.com/vitest-dev/vitest" target="_blank">
  <span class="remark-magic-link-icon" role="img" style="background-image: url('https://github.com/vitest-dev.png')"></span>
  <span class="remark-magic-link-text">Vitest</span>
</a>
dummy
<a class="remark-magic-link remark-magic-link-link remark-magic-link-with-icon" href="https://github.com/vuejs/core" target="_blank">
  <span class="remark-magic-link-icon" role="img" style="background-image: url('https://vuejs.org/logo.svg')"></span>
  <span class="remark-magic-link-text">Vue</span>
</a>

<a class="remark-magic-link remark-magic-link-link" href="https://github.com/unifiedjs/unified" target="_blank">
  <span class="remark-magic-link-text">Unified</span>
</a>

Paragraph

original

# Title

<a class="remark-magic-link remark-magic-link-link remark-magic-link-with-icon" href="https://github.com/vitest-dev/vitest" target="_blank"><span class="remark-magic-link-icon" role="img" style="background-image: url(&#x27;https://github.com/vitest-dev.png&#x27;)"></span><span class="remark-magic-link-text">Vitest</span></a> dummy <a class="remark-magic-link remark-magic-link-link remark-magic-link-with-icon" href="https://github.com/vuejs/core" target="_blank"><span class="remark-magic-link-icon" role="img" style="background-image: url(&#x27;https://vuejs.org/logo.svg&#x27;)"></span><span class="remark-magic-link-text">Vue</span></a>

<a class="remark-magic-link remark-magic-link-link" href="https://github.com/unifiedjs/unified" target="_blank"><span class="remark-magic-link-text">Unified</span></a>

Paragraph

Styling

It's unstyled by default, but a default style.css is provided.

import 'remark-magic-link/style.css';

It will transform {Vitest} into: Vitest

If you want to customize it yourself, the plugin generates a well-structured HTML output which can be styled via classnames.

Element	Classnames
<a> (root)	remark-magic-link | remark-magic-link-with-icon (if icon is not false)
<span> (icon)	remark-magic-link-icon
<span> (text)	remark-magic-link-text

Options

The only required option is linksMap if you are using the default handlers, which is an object where the keys are the texts to be matched and the values are the links and icons to be used.

Refer to API Reference for advanced usages.

TypeScript

This plugin is written in TypeScript and publishes its types.

Refer to Options or index.d.ts for detailed types.

Credits

Inspired by markdown-it-magic-link.