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

Auto-link references to commits, issues, pull-requests, and users like GitHub: Writing on GitHub.

Installation

npm:

npm install remark-github

Usage

var remark = require('remark');
var github = require('remark-github');

var input = [
  'References:',
  '',
  '* Commit: f8083175fe890cbf14f41d0a06e7aa35d4989587',
  '* Commit (fork): foo@f8083175fe890cbf14f41d0a06e7aa35d4989587.',
  '* Commit (repo): wooorm/remark@e1aa9f6c02de18b9459b7d269712bcb50183ce89.',
  '* Issue or PR (`#`): #1.',
  '* Issue or PR (`GH-`): GH-1.',
  '* Issue or PR (fork): foo#1.',
  '* Issue or PR (project): wooorm/remark#1.',
  '* Mention: @wooorm.',
  '',
  'Normalising of links:',
  '',
  '* Commit: https://github.com/wooorm/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89.',
  '* Commit comment: https://github.com/wooorm/remark/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693.',
  '* Issue or PR: https://github.com/wooorm/remark/issues/182',
  '* Issue or PR comment: https://github.com/wooorm/remark-github/issues/3#issue-151160339',
  '* Mention: @ben-eb.'
].join('\n');

console.log(remark().use(github).processSync(input).toString());

Yields:

References:

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

Normalising of links:

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

API

remark.use(github[, options])

Adds references to commits, issues, pull-requests, and users similar to how GitHub renders these in issues, comments, and pull request descriptions.

• Commits: 1f2a4fb — 1f2a4fb.
• Commits across forks: wooorm@1f2a4fb — wooorm@1f2a4fb.
• Commits across projects: wooorm/remark-github@1f2a4fb — wooorm/remark-github@1f2a4fb.
• Prefix issues: GH-1 — GH-1.
• Hash issues: #1 — #1.
• Issues across forks: wooorm#1 — wooorm#1.
• Issues across projects: wooorm/remark-github#1 — wooorm/remark-github#1.
• At-mentions: @mention and @wooorm. — @mention and @wooorm.

These links are generated relative to a project. In Node this is auto-detected by loading package.json and looking for a repository field. In the browser, or when overwriting this, you can pass a repository in options.

By default, mentions are wrapped in strong nodes (which 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 behaviour.

License

MIT © Titus Wormer