gatsby-remark-github

This is a plugin for gatsby-transformer-remark, which is in turn a plugin for GatsbyJS. This plugin is a simple wrapper around the remark-github-plugin, which replace links to GitHub files in Markdown 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. gatsby-remark-prismjs). For more details on how this package came about, you can read about its development process in my series of blog posts.

Installation

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

Note: You need to install remark-github-plugin along with this package because it is a peer dependency.

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).

If you haven't already installed gatsby-transformer-remark, you should install it. If you want to have syntax highlighting by PrismJS, install gatsby-remark-prismjs as well.

Then in your gatsby-config.js, add this plugin to the list of plugins for gatsby-transformer-remark, preferably as the first one but definitely before gatsby-remark-prismjs:

module.exports = {
  // other configs ...
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: 'gatsby-remark-github',
            options: {
              marker: 'GITHUB-EMBED',
              insertEllipsisComments: true,
              ellipsisPhrase: '...',
              useCache: true,
              cacheKey: 'gatsby-remark-github-v1',
              token: '<Your Github Token, preferably read from an environment variable>',
            }
          },
          // ... other plugins ...
          'gatsby-remark-prismjs',
        ]
      }
    }
  ]
}

For sample input and output, please refer to the usage section of remark-github-plugin. You can also find a full real-world setup in this repo.

Configuration

This plugin takes the exact same configuration as that of remark-github-plugin.