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

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

Usage

Dependencies:

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

Input:

var input = [
    '* SHA: 1f2a4fb8f88a0a98ea9d0c0522cd538a9898f921',
    '* User@SHA: jlord@1f2a4fb8f88a0a98ea9d0c0522cd538a9898f921',
    '* User/Repository@SHA: jlord/sheetsee.js@1f2a4fb',
    '* #Num: #1',
    '* GH-Num: GH-1',
    '* User#Num: jlord#1',
    '* User/Repository#Num: jlord/sheetsee.js#1',
    '* @mention',
    '* And @mentioning someone else',
    '* And nothing'
].join('\n');

Process:

var file = remark.process(input);

Yields:

-   SHA: [`1f2a4fb`](https://github.com/wooorm/remark-github/commit/1f2a4fb8f88a0a98ea9d0c0522cd538a9898f921)
-   User@SHA: [jlord@`1f2a4fb`](https://github.com/jlord/remark-github/commit/1f2a4fb8f88a0a98ea9d0c0522cd538a9898f921)
-   User/Repository@SHA: [jlord/sheetsee.js@`1f2a4fb`](https://github.com/jlord/sheetsee.js/commit/1f2a4fb)
-   \#Num: [#1](https://github.com/wooorm/remark-github/issues/1)
-   GH-Num: [GH-1](https://github.com/wooorm/remark-github/issues/1)
-   User#Num: [jlord#1](https://github.com/jlord/remark-github/issues/1)
-   User/Repository#Num: [jlord/sheetsee.js#1](https://github.com/jlord/sheetsee.js/issues/1)
-   [**@mention**](https://github.com/blog/821)
-   And [**@mentioning**](https://github.com/mentioning) someone else
-   And nothing

API

remark.use(commentConfig[, options])

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

• SHA commits references: 1f2a4fb — 1f2a4fb
• User@SHA: wooorm@1f2a4fb — wooorm@1f2a4fb
• User/Repository@SHA: wooorm/remark-github@1f2a4fb — wooorm/remark-github@1f2a4fb
• Hash-Num: #1 — #1
• GH-Num: GH-1 — GH-1
• User#Num: wooorm#1 — wooorm#1
• User/Repository#Num: 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.

License

MIT © Titus Wormer