No commit activity in last 3 years
No release in over 3 years
Asciidoctor extension for including files from private GitHub repos
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Runtime

>= 1.5.0, ~> 1.5
 Project Readme

AsciiDoctor GitHub includes extension

This AsciiDoctor extension lets you include files directly from remote GitHub repositories. It will only affect include directives for URIs beginning with https://raw.githubusercontent.com.

Installation

With Ruby Gems:

gem install asciidoctor-github-include

Usage

Command line

Load the extension, and pass a GitHub personal access token as an attribute named github-access-token:

asciidoctor -r asciidoctor-github-include -a github-access-token=yourtoken [file.adoc]

Then, inside your AsciiDoc file, use an include statement like normal, pointing to a URI that begins with https://raw.githubusercontent.com.

If you set up an access token (by setting the github-access-token attribute), it must be a valid access token—​even for accessing public repos. This is because GitHub returns 404 on all requests that pass invalid tokens.

If github-access-token is left undefined, however, fetching from public repositories will still work.

Examples

Basic

Save this 1-line Asciidoc file as readme.adoc:

include::https://raw.githubusercontent.com/tkfu/asciidoctor-github-include/master/README.adoc[]

Then run

asciidoctor -r asciidoctor-github-include -a github-access-token=yourtoken readme.adoc

and open readme.html in your browser. You should be looking at this readme!

Retrieve specific branches using attributes

A useful way to set up your AsciiDoc file when using asciidoctor-github-include is something like this:

= GitHub Use
:repo-stem: https://raw.githubusercontent.com/my_username/my_private_repo
:ref: master
:my_private_repo: {repo-stem}/{ref}

include::{my_private_repo}/path/to/included.adoc[]

Then, generate the doc:

asciidoctor -r asciidoctor-github-include -a github-access-token=yourtoken [file.adoc]

Later on, you may want to generate docs from a different branch. For that, you can override the ref attribute from the command line:

asciidoctor -r asciidoctor-github-include -a github-access-token=yourtoken -a ref=v1.2.3 [file.adoc]

Valid values for ref here are anything that works for git checkout: a branch name, a tag, or a commit SHA—​even a shortened one.

Use this extension with Jekyll

One of the reasons this extension exists is to allow the easy generation of Jekyll-based documentation sites that need to fetch resources from various other git repos. However, you can’t pass attributes into jekyll-asciidoc from the command line. To work around this, we use a secondary, secret config file.

Prerequisites

In your Gemfile:

gem 'jekyll-asciidoc'
gem 'asciidoctor-github-include'

In your _config.yml:

plugins:
  - jekyll-asciidoc
  - asciidoctor-github-include

In a new file called _secret.yml:

asciidoctor:
  attributes:
    github-access-token: yourtoken

yourtoken is a personal access token for command line usage that you’ve generated.

In your .gitignore:

_secret.yml

Generating the site

Pass the secret config file to jekyll build:

jekyll build --config _config.yml,_secret.yml

Bugs and omissions

Unsupported features

Partially supported features

  • Include by tagged regions

    • You can’t use tagged regions and line ranges together. If you specify both, the tags will be ignored.

    • Only the first region matching each tag you pass in is retrieved. If you have multiple regions with the same tag, everything except the first will be ignored.

    • When using multiple tags via include::[tags=foo;bar], tagged regions are added in the order specified, not the order they originally appear in the source file.

Example of the behaviour difference compared to native AsciiDoctor includes:

Source file contents
// tag::foo[]

Lorem ipsum part 1

// end::foo[]

Some text I don't care about

// tag::bar[]

Lorem ipsum part 2

// end::bar[]

// tag::foo[]

Lorem ipsum part 3

// end::foo[]
Text yielded by include::https://raw.githubusercontent.com/path/to/file[tags=bar;foo]
Lorem ipsum part 2


Lorem ipsum part 1
Text yielded by native AsciiDoctor include::/path/to/file[tags=bar;foo]
Lorem ipsum part 1


Lorem ipsum part 2



Lorem ipsum part 3