markdown-it-handle

Links to users across different social networks using markdown-it and the handle format @username@host.

Requirements

Node.js v16 or later.

Installation

npm install markdown-it-handle

Usage

const md = require('markdown-it')

md.use(require('markdown-it-handle'))

This plugin converts the format used for username handles common to federated social networks, into linked usernames.

For example, given this Markdown:

@[email protected], @[email protected] and @[email protected].

the following markup will be generated (lines wrapped for clarity):

<p>
  <a href="https://micro.blog/paulrobertlloyd" rel="external">@paulrobertlloyd</a>,
  <a href="https://twitter.com/paulrobertlloyd" rel="external">@paulrobertlloyd</a> and
  <a href="https://mastodon.social/@paulrobertlloyd" rel="external">@paulrobertlloyd</a>.
</p>

This can be particularly useful if you are syndicating plain-text posts using Markdown, but rendering them on your own site as HTML.

Syndicated text containing handles will get parsed as mentions by the federated server, while readable link text is shown to readers on your own website.

Options

Link attributes

By default, links include a rel="external" attribute. To override this behaviour, set the attributes option to false:

md.use(require('markdown-it-handle'), {
  attributes: false
})

marked('@[email protected]')

This will output:

<p><a href="https://social.example/@username">@username</a></p>

You can add or update attributes used on handle links by providing them in the attributes option:

md.use(require('markdown-it-handle'), {
  attributes: {
    class: 'handle',
    rel: 'external nofollow',
    target: '_blank',
  }
})

marked('@[email protected]')

This will output:

<p><a href="https://social.example/@username" class="handle" rel="external nofollow" target="_blank">@username</a></p>

URL prefixes

Most federated networks include the @ symbol in profile URLs but older and non-federated networks do not. Meanwhile, some networks use a common path for user profiles. For example:

By default, usernames are linked to URLs using first format using the @ symbol. A list of common social networks that dont use this format is provided in /lib/prefixes.js. These values can be overridden and extended.

For example, if you want a Flickr usernames to link to profile pages instead of photo pages, you can update the prefixes option as follows:

md.use(require('markdown-it-handle'), {
  prefixes: {
    'flickr.com': 'people/',
  }
})

marked('@[email protected]')

This will output:

<p><a href="https://flickr.com/people/username" rel="external">@username</a></p>

Releasing new versions

The recommended way to release new versions of this package is using np. This can be run using the following command:

npm run release

Credits

Inspired by an original idea by Cdric Aellen.