Usage

Add this to your gitbook's configuration file to enable the plugin:

// book.js
{
  plugins: ['github-embed']
}

To configure the plugin:

// book.js
{
  pluginsConfig: {
    'github-embed': {
      showLink: boolean [default=true]
      reindent: boolean [default=true]
      cacheDir: string [default=undefined]
    }
  }
}

Embed Github Snippets into Gitbooks

Embed snippet text or whole files from Github repos into a GitBook.

{% github_embed "[github url]", [options] %}{% endgithub_embed %}

Where [github url] is:

https://github.com/[owner]/[repo]/blob/[ref]/[path]#[line numbers]

(You can also provide the url to a Github Enterprise installation)

Will produce something like this given the URL: https://github.com/v5analytics/gitbook-plugin-github-embed/blob/1cd16ac/index.js#L3-L8

website: {
    assets: "./book",
    css: [
        "github-embed.css"
    ]
},

index.js (lines 3–8)

Examples

// Load latest version of file "tag.js"   
{% github_embed "https://github.com/v5analytics/gitbook-plugin-github-embed/blob/master/src/tag.js" %}{% endgithub_embed %}

// Load latest version of file "tag.js" and show line 3
{% github_embed "https://github.com/v5analytics/gitbook-plugin-github-embed/blob/master/src/tag.js#L3" %}{% endgithub_embed %}

// Load latest version of file "tag.js" and show lines 1-5   
{% github_embed "https://github.com/v5analytics/gitbook-plugin-github-embed/blob/master/src/tag.js#L1-L5" %}{% endgithub_embed %}

// Load specific version of file "tag.js" and show lines 1-5   
// Press "Y" key in github to switch from master/latest to last commit
{% github_embed "https://github.com/v5analytics/gitbook-plugin-github-embed/blob/9ef6e532/src/tag.js#L1-L5" %}{% endgithub_embed %}

// Load full file, but hide interior lines
{% github_embed "https://github.com/v5analytics/gitbook-plugin-github-embed/blob/9ef6e532/src/tag.js", hideLines=['15-87'] %}{% endgithub_embed %}

Gitbook Block Options

Keywords specified in embedded snippets will override plugin configuration specified in book.js

• showLink=true Show a link below the embedded source back to the source file. Defaults to true

    {% github_embed "[url]", showLink=false %}{% endgithub_embed %}

• reindent=true Re-indent the lines given the line numbers. Defaults to true

    {% github_embed "[url]", reindent=false, showLink=false %}{% endgithub_embed %}

• hideLines=[] Hide interior lines in a snippet. Should be in ascending order, can contain a range as a string.

    {% github_embed "[url]", hideLines=[2, '4', '7-10'] %}{% endgithub_embed %}

Styling the Link

Use a gitbook style override to adjust the style of the link. The class is .github-embed-caption.

Avoiding Rate Limit Errors

Set an environment variable to avoid rate limits. Create Token

GITBOOK_EMBED_GITHUB_API_TOKEN=[API Token]
# or
GITHUB_API_TOKEN=[API Token]

Adding Configuration For Multiple Github Resources

If you want to provide different configuration for different urls (for instance if you are embedding links to both a public and private repository and would like to use different tokens) you can add it to the plugin configuration like so:

// book.js
{
  pluginsConfig: {
    'github-embed': {
      showLink: false,
      urls: [
        {
          regex: /github\.com\/owner\/repo1/,
          token: '<Github API token>',
          showLink: true
        },
        {
          regex: /github\.com\/owner\/repo2/,
          token: '<Github API token>'
        }
      ]
    }
  }
}

If the plugin finds a link that matches the url configuration regex it will use that configuration.

You can also specify a github key to pass arguments to the github api client

urls: [
  {
    regex: /github\.com\/owner\/repo1/,
    token: '<Github API token>',
    github: {
      // https://github.com/octokit/rest.js#client-options
    }
    showLink: true
  },
]