website/gems/lib/asciidoctor/github-raw-content-include-processor/README.adoc

Table of Contents

• Extra notes
• Attributes
• Example usage

This is a include processor for easily including files from GitHub. Take note this will only include files. For directories, submodules, or symlinks: they will not be processed and a warning will be issued.

This extension honors the safe mode setting and the prerequisites for permitting includes with URI.

The following is the basic form of using this include processor.

include::github:$OWNER/$REPO[]

Extra notes

The include processor will use GitHub API. It can create authorized requests by setting a token in GITHUB_API_BEARER_TOKEN environment variable. For instructions on how to get a token, you can refer to respective documentation.

Attributes

• path for the path of the file to be included. This is practically required as the root entry of the repository is a directory.

• rev is the name of the commit/tag/branch to be checked out.

Example usage

• include::github:asciidoctor/asciidoctor[path=README.adoc, rev=v2.0.0] will include the Asciidoc file from the Asciidoctor GitHub repo from the point of v2.0.0.

• include::github:NixOS/nixpkgs[path=shell.nix] will get the latest revision of shell.nix from nixpkgs repository.

• include::github:foo-dogsquared/nixos-config[] should not be processed considering it points to the root directory of the repository.