metalsmith-safe-links

Metalsmith plugin to strip <protocol://hostname> from local links and to add target and rel attributes to external links.

As markdown syntax only allows for alt and title attributes, content editors normally must use HTML to add other link attributes. This plugin negates the use of HTML for links in a markdown document.

Installation

npm i metalsmith-safe-links

Usage

This plugin must be used after markdown has been transformed into html

This plugin supports both ESM and CommonJS environments.

ESM (ECMAScript Modules)

import metalsmith from 'metalsmith';
import markdown from '@metalsmith/markdown';
import layouts from '@metalsmith/layouts';
import metalsmithSafeLinks from 'metalsmith-safe-links';

metalsmith(__dirname)
  .use(markdown())
  .use(layouts())
  .use(
    metalsmithSafeLinks({
      hostnames: ['www.livesite.com', 'stagingsite.com']
    })
  )
  .build();

CommonJS

const metalsmith = require('metalsmith');
const markdown = require('@metalsmith/markdown');
const layouts = require('@metalsmith/layouts');
const metalsmithSafeLinks = require('metalsmith-safe-links');

metalsmith(__dirname)
  .use(markdown())
  .use(layouts())
  .use(
    metalsmithSafeLinks({
      hostnames: ['www.livesite.com', 'stagingsite.com']
    })
  )
  .build();

Options

• hostNames [array] - an array of hostnames. The plugin will strip <protocol://hostname> from all links with these names.

Example

An internal markdown link

[Go to this page](https://www.livesite.com/this-page/)

will be transformed into

<a href="/this-page/">Go to this page</a>

An external markdown link

[Go to this site](https://www.externalsite.com/)

will be transformed into

<a href="https://www.externalsite.com/" target="_blank" rel="noopener noreferrer">Go to this site</a>

Debug

To log debug output, set the DEBUG environment variable to metalsmith-safe-links"

Linux/Mac:

DEBUG = metalsmith - safe - links;

Windows:

set DEBUG=metalsmith-safe-links

CLI usage

To use this plugin with the Metalsmith CLI, add metalsmith-safe-links to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "metalsmith-safe-links": {
        "hostnames": ["www.livesite.com", "stagingsite.com"]
      }
    }
  ]
}

Test Coverage

This plugin maintains high statement and line coverage for the source code. Coverage is automatically verified and updated on each push to the main branch using GitHub Actions. The coverage badge at the top of this README reflects the current test coverage.

Authors

werner@glinka.co

License

Code released under the ISC license.