remark plugin to link references to commits, issues, and users, in the
same way that GitHub does in comments, issues, PRs, and releases (see Writing
on GitHub).
This package is a unified (remark) plugin to link references to commits,
issues, and users: @wooorm -> [**@wooorm**](https://github.com/wooorm).
When should I use this?
This project is useful if you want to emulate how markdown would work in GitHub
comments, issues, PRs, or releases, but it’s actually displayed somewhere else
(on a website, or in other places on GitHub which don’t link references, such as
markdown in a repo or Gist).
This plugin does not support other platforms such as GitLab or Bitbucket and
their custom features.
A different plugin, remark-gfm, adds support for GFM (GitHub
Flavored Markdown).
GFM is a set of extensions (autolink literals, footnotes, strikethrough, tables,
and tasklists) to markdown that are supported everywhere on GitHub.
Another plugin, remark-breaks, turns soft line endings
(enters) into hard breaks (<br>s).
GitHub does this in a few places (comments, issues, PRs, and releases), but it’s
not semantic according to HTML and not compliant to markdown.
Yet another plugin, remark-frontmatter, adds support
for YAML frontmatter.
GitHub supports frontmatter for files in Gists and repos.
Install
This package is ESM only.
In Node.js (version 16+), install with npm:
mentionStrong (boolean, default: true)
— wrap mentions in strong;
this makes them render more like how GitHub styles them, but GH itself
uses CSS instead of strong
repository (string, default: repository from packag.json in CWD in
Node, otherwise required)
— repository to link against;
should point to a GitHub repository (such as 'user/project')
Examples
Example: buildUrl
A buildUrl can be passed to not link mentions.
For example, by changing example.js from before like so:
@@ -1,11 +1,15 @@ import {remark} from 'remark' import remarkGfm from 'remark-gfm'-import remarkGithub from 'remark-github'+import remarkGithub, {defaultBuildUrl} from 'remark-github' import {read} from 'to-vfile' const file = await remark() .use(remarkGfm)- .use(remarkGithub)+ .use(remarkGithub, {+ buildUrl(values) {+ return values.type === 'mention' ? false : defaultBuildUrl(values)+ }+ }) .process(await read('example.md')) console.log(String(file))
To instead point mentions to a different place, change example.js like so:
@@ -1,11 +1,17 @@ import {remark} from 'remark' import remarkGfm from 'remark-gfm'-import remarkGithub from 'remark-github'+import remarkGithub, {defaultBuildUrl} from 'remark-github' import {read} from 'to-vfile' const file = await remark() .use(remarkGfm)- .use(remarkGithub)+ .use(remarkGithub, {+ buildUrl(values) {+ return values.type === 'mention'+ ? `https://yourwebsite.com/${values.user}/`+ : defaultBuildUrl(values)+ }+ }) .process(await read('example.md')) console.log(String(file))
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, remark-github@^12,
compatible with Node.js 16.
This plugin works with unified version 6+ and remark version 7+.
Security
Use of remark-github does not involve rehype (hast).
It does inject links based on user content, but those links only go to GitHub.
There are no openings for cross-site scripting (XSS) attacks.
Related
remark-gfm
— support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)
remark-breaks
— support breaks without needing spaces or escapes (enters to <br>)