remark-autolink-references

remark plugin to autolink custom references like GitHub Pro does. Ideal for referencing external issue trackers in changelogs.

Install

With npm do:

npm install remark-autolink-references

Usage with `remark`

This package is ESM-only.

import remark from 'remark'
import autolink from 'remark-autolink-references'

remark()
  .use(autolink, {
    prefix: 'JIRA-',
    url: 'https://example.atlassian.net/browse/JIRA-<num>'
  })
  .process('Example (JIRA-4275)', function (err, file) {
    console.log(String(file))
  })

Results in:

- Example ([JIRA-4275](https://example.atlassian.net/browse/JIRA-4275))

Set fix to false to only warn about unlinked references, thus acting as a linter:

remark()
  .use(autolink, {
    prefix: 'JIRA-',
    url: 'https://example.atlassian.net/browse/JIRA-<num>',
    fix: false
  })

Usage with `hallmark`

This plugin is included in hallmark >= 3.1.0. It does nothing until configured via package.json or .hallmarkrc. Say we have the following markdown in a CHANGELOG.md with a reference to a Jira ticket:

### Fixed

- Prevent infinite loop (JIRA-4275)

Our package.json should look like this:

{
  "name": "example",
  "devDependencies": {
    "hallmark": "^3.1.0",
  },
  "hallmark": {
    "autolinkReferences": {
      "prefix": "JIRA-",
      "url": "https://example.atlassian.net/browse/JIRA-<num>"
    }
  }
}

Alternatively we can create a .hallmarkrc file containing:

{
  "autolinkReferences": {
    "prefix": "JIRA-",
    "url": "https://example.atlassian.net/browse/JIRA-<num>"
  }
}

Running npx hallmark fix then yields:

### Fixed

- Prevent infinite loop ([JIRA-4275](https://example.atlassian.net/browse/JIRA-4275))

While npx hallmark lint will warn about unlinked references.

API

`autolink(options)`

Options:

prefix (string, required): this prefix appended by a number will generate a link
url (string, required): where to link to. Must contain <num> for the reference number.
fix (boolean, default true): if false, lint without modifying the markdown. Will warn about unlinked references.