asciidoctor-foodogsquared-e.../lib/asciidoctor/gitlab-raw-content-include-processor/README.adoc

= GitLab raw content include processor
:toc:


It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.


== Synopsis

[source, asciidoc]
----
include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]
----


== Extra notes

A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.
Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.


== Attributes

There are some attributes required to be passed.

- `rev` is the commit to be checked out.
- `path` is the file path to be included.

Aside from the required attributes, there are optional attributes to configured further.

- `domain` is the domain of the GitLab instance.
By default, it points to the `gitlab.com` official instance.

- `version` is the version string of the API to be used.
By default, it uses version `v4`.


== Example usage

- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].

- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].

- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.
Add GitLab raw content include processor 2023-03-05 05:48:40 +00:00			`= GitLab raw content include processor`
			`:toc:`


			`It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.`


			`== Synopsis`

			`[source, asciidoc]`
			`----`
			`include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]`
			`----`


			`== Extra notes`

			`A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.`
			Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.


			`== Attributes`

			`There are some attributes required to be passed.`

			- `rev` is the commit to be checked out.
			- `path` is the file path to be included.

			`Aside from the required attributes, there are optional attributes to configured further.`

			- `domain` is the domain of the GitLab instance.
			By default, it points to the `gitlab.com` official instance.

			- `version` is the version string of the API to be used.
			By default, it uses version `v4`.


			`== Example usage`

Update documentation for various Asciidoctor extensions 2023-04-16 03:06:10 +00:00			- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].

			- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].

			- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.