= GitHub raw content include processor
:toc:


This is a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[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 link:https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/[safe mode setting] and link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[the prerequisites for permitting includes with URI].

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

[source, asciidoc]
----
include::github:$OWNER/$REPO[]
----


== 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 link:https://github.com/asciidoctor/asciidoctor/[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 link:https://github.com/NixOS/nixpkgs[nixpkgs repository].

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