mirror of
https://github.com/foo-dogsquared/website.git
synced 2025-01-31 16:58:03 +00:00
41 lines
1.8 KiB
Plaintext
41 lines
1.8 KiB
Plaintext
= 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.
|