unified

Project:huy-nguyen/remark-github-plugin

Package:remark-github-plugin@1.3.1

  1. Dependencies:6ยทDependents:0
  2. Remark plugin to inline GitHub source code into markdown file as code blocks
  1. remark 181
  2. unified 135
  3. plugin 123
  4. remark-plugin 65
  5. github 6

remark-github-plugin

Greenkeeper badge

npm tested with jest CircleCI codecov

This remark plugin replace links to GitHub files with the actual content of those files, wrapped in Markdown code blocks that can optionally be further processed by a syntax highlighter (e.g. Prism).

Prerequisites

Installation

Install with npm or yarn:

npm install remark-github-plugin
# or:
yarn add remark-github-plugin

Usage

First, create a GitHub personal access token with the public_repo scope (if you only need to access public repos) or repo scope (if you need to also access private repos).

const {plugin} = require('remark-github-plugin');
const remark = require('remark');

const pluginOptions = {
  marker: 'GITHUB-EMBED',
  insertEllipsisComments: true,
  ellipsisPhrase: '...',
  useCache: true,
  cacheKey: 'remark-github-plugin-v1',
  token: '<Your Github Token>',
}

const processor = remark().data(

  // This is optional but recommended. If `fences` is `true`, code blocks with
  // no explicitly set language will be rendered as code blocks. Othewise, they
  // will be rendered as text.
  'settings', {fences: true}
).use(
  plugin, pluginOptions
)

// Read file content:
const fs = require('fs');
const input = fs.readFileSync('path/to/some/markdown/file.md');

// Process input with plugin:
process.process(input, (err, output) => {
  if (err) {
    throw new Error(err);
  }

  console.log(output.contents);
})

Sample input and output

To embed a GitHub file, copy theURL of that file from the browser's location bar and paste it into a new Markdown paragraph that begins and ends with the marker phrase. Preferably, that URL should be a permanent link so that the content you're pointing to doesn't change without your knowledge in the future.

For example, with the above config, to embed the file https://github.com/lodash/lodash/blob/2900cfd/sumBy.js, do this:

Sample input with no language and no line range

This is the Markdown output of the plugin:

Sample output with no language and no line range

You can specify what syntax highlighting should be used by adding a PrismJs-compatible language code:

Sample input with language but no line range

This is the Markdown output of the plugin:

Sample output with language but no line range

You can even pick out individual lines or line ranges from the file.

Sample input with language and line range

In this case, we picked line 1, line 2 and lines 27 through 31. This is the Markdown output of the plugin:

Sample output with language and line range

For a list of supported line range notations, click here.

Configuration

Contributors

Thanks goes to these people (emoji key):


Huy Nguyen

๐Ÿ“ ๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿš‡ ๐Ÿ‘€ โš ๏ธ ๐Ÿ”ง โœ…

This project follows the all-contributors specification. Contributions of any kind welcome!