remark-github

What is remark-github?

The remark-github package is a plugin for remark (a Markdown processor) that automatically links references to GitHub issues, pull requests, and users in Markdown files. It enhances Markdown documents by converting GitHub references into clickable links, making it easier to navigate and understand the context of the references.

What are remark-github's main functionalities?

Linking GitHub Issues and Pull Requests

This feature allows you to automatically convert references to GitHub issues and pull requests into clickable links. In the example, the text 'This is a reference to issue #42' will be converted to a link pointing to the issue number 42 in the specified repository.

const remark = require('remark');
const remarkGithub = require('remark-github');

remark()
  .use(remarkGithub, { repository: 'user/repo' })
  .process('This is a reference to issue #42', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Linking GitHub Users

This feature allows you to automatically convert references to GitHub users into clickable links. In the example, the text 'This is a reference to @username' will be converted to a link pointing to the GitHub profile of the specified user.

const remark = require('remark');
const remarkGithub = require('remark-github');

remark()
  .use(remarkGithub, { repository: 'user/repo' })
  .process('This is a reference to @username', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to remark-github

remark-mentions

The remark-mentions package is a plugin for remark that converts @mentions in Markdown to links. It is similar to remark-github in that it provides automatic linking for user mentions, but it does not handle issue or pull request references.

remark-autolink-headings

The remark-autolink-headings package is a plugin for remark that automatically adds links to headings in Markdown files. While it does not specifically target GitHub references, it provides similar functionality in terms of enhancing Markdown documents with automatic links.

remark-slug

The remark-slug package is a plugin for remark that adds slugs to headings in Markdown files, making them linkable. This package is useful for creating anchor links within a document, but it does not provide the GitHub-specific linking features of remark-github.

README

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: remarkjs@e2acebc...2aa9311 → remarkjs/remark-github@e2acebc...2aa9311
• Compare ranges across projects: remarkjs/remark-github@e2acebc...2aa9311 → 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.

Custom URLs

By default we build URLs to public GitHub. You can overwrite them to point to GitHub Enterprise or other places by passing a buildUrl. That function is given an object with different values and the default buildUrl. If buildUrl returns false, the value is not linked.

remark()
  .use(remarkGithub, {
    // The fields in `values` depends on the kind reference:
    // {type: 'commit', user, project, hash}
    // {type: 'compare', user, project, base, compare}
    // {type: 'issue', user, project, no}
    // {type: 'mention', user}
    // You can return a URL, which will be used, or `false`, to not link.
    buildUrl(values, defaultBuildUrl) {
      return values.type === 'mention'
        ? `https://yourwebsite.com/${values.user}/`
        : defaultBuildUrl(values)
    }
  })

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