Skip to content

A remark plugin to autolink custom references.

License

Notifications You must be signed in to change notification settings

vweevers/remark-autolink-references

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

11 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

remark-autolink-references

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

npm status node Test JavaScript Style Guide Markdown Style Guide Common Changelog

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:

Click to expand
{
  "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.

License

MIT.

Adapted from remark-github © 2015 Titus Wormer.