evhaus / remark-github

plugin to autolink references to commits, issues, pull-requests, and users, like on GitHub

remark-github

remark plugin to automatically link references to commits, issues, pull-requests, and users, like in GitHub issues, PRs, and comments (see Writing on GitHub).

Note!

This plugin is ready for the new parser in remark (micromark, see remarkjs/remark#536). Version 10 works with old (12) and new (13+) remark!

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install remark-github

Use

Say we have the following file, example.md:

Some references:

*   Commit: f8083175fe890cbf14f41d0a06e7aa35d4989587
*   Commit (fork): foo@f8083175fe890cbf14f41d0a06e7aa35d4989587
*   Commit (repo): remarkjs/remark@e1aa9f6c02de18b9459b7d269712bcb50183ce89
*   Issue or PR (`#`): #1
*   Issue or PR (`GH-`): GH-1
*   Issue or PR (fork): foo#1
*   Issue or PR (project): remarkjs/remark#1
*   Mention: @wooorm

Some links:

*   Commit: <https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89>
*   Commit comment: <https://github.com/remarkjs/remark/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693>
*   Issue or PR: <https://github.com/remarkjs/remark/issues/182>
*   Issue or PR comment: <https://github.com/remarkjs/remark-github/issues/3#issue-151160339>
*   Mention: <https://github.com/ben-eb>

And our module, example.js, looks as follows:

import {readSync} from 'to-vfile'
import {remark} from 'remark'
import remarkGithub from 'remark-github'

const file = readSync('example.md')

remark()
  .use(remarkGithub)
  .process(file)
  .then((file) => {
    console.log(String(file))
  })

Now, running node example yields:

Some references:

*   Commit: [`f808317`](https://github.com/remarkjs/remark-github/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
*   Commit (fork): [foo@`f808317`](https://github.com/foo/remark-github/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
*   Commit (repo): [remarkjs/remark@`e1aa9f6`](https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
*   Issue or PR (`#`): [#1](https://github.com/remarkjs/remark-github/issues/1)
*   Issue or PR (`GH-`): [GH-1](https://github.com/remarkjs/remark-github/issues/1)
*   Issue or PR (fork): [foo#1](https://github.com/foo/remark-github/issues/1)
*   Issue or PR (project): [remarkjs/remark#1](https://github.com/remarkjs/remark/issues/1)
*   Mention: [**@wooorm**](https://github.com/wooorm)

Some links:

*   Commit: [remarkjs/remark@`e1aa9f6`](https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
*   Commit comment: [remarkjs/remark@`ac63bc3` (comment)](https://github.com/remarkjs/remark/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693)
*   Issue or PR: [remarkjs/remark#182](https://github.com/remarkjs/remark/issues/182)
*   Issue or PR comment: [#3 (comment)](https://github.com/remarkjs/remark-github/issues/3#issue-151160339)
*   Mention: <https://github.com/ben-eb>

API

This package exports no identifiers. The default export is remarkGithub.

unified().use(remarkGithub[, options])

Automatically link references to commits, issues, pull-requests, and users, like in GitHub issues, PRs, and comments (see Writing on GitHub).

Conversion

• Commits: 1f2a4fb → 1f2a4fb
• Commits across forks: remarkjs@1f2a4fb → remarkjs@1f2a4fb
• Commits across projects: remarkjs/remark-github@1f2a4fb → remarkjs/remark-github@1f2a4fb
• Compare ranges: e2acebc...2aa9311 → e2acebc...2aa9311
• Compare ranges across forks: [email protected] → remarkjs/remark-github@e2acebc...2aa9311
• Compare ranges across projects: remarkjs/[email protected] → remarkjs/remark-github@e2acebc...2aa9311
• Prefix issues: GH-1 → GH-1
• Hash issues: #1 → #1
• Issues across forks: remarkjs#1 → remarkjs#1
• Issues across projects: remarkjs/remark-github#1 → remarkjs/remark-github#1
• At-mentions: @wooorm → @wooorm

Repository

These links are generated relative to a project. In Node this is detected automatically by loading package.json and looking for a repository field. In the browser, or when overwriting this, you can pass a repository in options. The value of repository should be a URL to a GitHub repository, such as 'https://github.com/user/project.git', or only 'user/project'.

Mentions

By default, mentions are wrapped in strong nodes (that render to <strong> in HTML), to simulate the look of mentions on GitHub. However, this creates different HTML markup, as the GitHub site applies these styles using CSS. Pass mentionStrong: false to turn off this behavior.

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.

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer