= 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[]
----


== 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 link:https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api?apiVersion=2022-11-28#authenticating[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 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.
