https://github.com/vweevers/remark-autolink-references
A remark plugin to autolink custom references.
https://github.com/vweevers/remark-autolink-references
github jira markdown nodejs remark remark-plugin
Last synced: 9 months ago
JSON representation
A remark plugin to autolink custom references.
- Host: GitHub
- URL: https://github.com/vweevers/remark-autolink-references
- Owner: vweevers
- License: mit
- Created: 2020-11-14T08:22:20.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-10-01T18:30:04.000Z (over 2 years ago)
- Last Synced: 2025-09-07T06:29:35.278Z (9 months ago)
- Topics: github, jira, markdown, nodejs, remark, remark-plugin
- Language: JavaScript
- Homepage:
- Size: 23.4 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# remark-autolink-references
**[`remark`](https://github.com/remarkjs/remark) plugin to autolink custom references like [GitHub Pro](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/configuring-autolinks-to-reference-external-resources) does.** Ideal for referencing external issue trackers in changelogs.
[](https://www.npmjs.org/package/remark-autolink-references)
[](https://www.npmjs.org/package/remark-autolink-references)
[](https://github.com/vweevers/remark-autolink-references/actions/workflows/test.yml)
[](https://standardjs.com)
[](https://github.com/vweevers/hallmark)
[](https://common-changelog.org)
## Install
With [npm](https://npmjs.org) do:
```
npm install remark-autolink-references
```
## Usage with [`remark`](https://remark.js.org/)
_This package is ESM-only._
```js
import remark from 'remark'
import autolink from 'remark-autolink-references'
remark()
.use(autolink, {
prefix: 'JIRA-',
url: 'https://example.atlassian.net/browse/JIRA-'
})
.process('Example (JIRA-4275)', function (err, file) {
console.log(String(file))
})
```
Results in:
```md
- 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:
```js
remark()
.use(autolink, {
prefix: 'JIRA-',
url: 'https://example.atlassian.net/browse/JIRA-',
fix: false
})
```
## Usage with [`hallmark`](https://github.com/vweevers/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:
```md
### Fixed
- Prevent infinite loop (JIRA-4275)
```
Our `package.json` should look like this:
```json
{
"name": "example",
"devDependencies": {
"hallmark": "^3.1.0",
},
"hallmark": {
"autolinkReferences": {
"prefix": "JIRA-",
"url": "https://example.atlassian.net/browse/JIRA-"
}
}
}
```
Alternatively we can create a `.hallmarkrc` file containing:
Click to expand
```json
{
"autolinkReferences": {
"prefix": "JIRA-",
"url": "https://example.atlassian.net/browse/JIRA-"
}
}
```
Running `npx hallmark fix` then yields:
```md
### 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 `` for the reference number.
- `fix` (boolean, default true): if false, lint without modifying the markdown. Will warn about unlinked references.
## License
[MIT](LICENSE).
Adapted from [`remark-github`](https://github.com/remarkjs/remark-github) © 2015 Titus Wormer.