remark-github

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

Installation

npm:

npm install remark-github

remark-github is also available as an AMD, CommonJS, and globals module, uncompressed and compressed.

Usage

Dependencies:

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

Processor:

var processor = remark().use(github);

Input:

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');

Process:

var doc = processor.process(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