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 If |
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
-
Tag filtering, including negated tags (
tag=!mytag)
Partially supported features
-
-
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:
// 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[]
include::https://raw.githubusercontent.com/path/to/file[tags=bar;foo]
Lorem ipsum part 2 Lorem ipsum part 1
include::/path/to/file[tags=bar;foo]
Lorem ipsum part 1 Lorem ipsum part 2 Lorem ipsum part 3