= SWHID include processor
:toc:


This is an include processor extension for easily fetching SWHIDs, only with the `cnt` schema type.


== Synopsis

[source, asciidoc]
----
\include::$SWHID[]
----

Where `$SWHID` is a link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHID].
This could accept SWHIDs with qualifiers.

Take note this include processor will only give the raw content with the `cnt` schema type.
Anything else will be skipped and log a warning instead.



== Extra notes

[source, asciidoc]
----
= doctitle
:swhid-gpl3: swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2

\include::{swhid-nixpkgs}[]
----

This include processor also respects the safe mode setting.
This means in order to permit including by SWHID, you have to permit link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[includes by URIs].

Lastly, this include processor uses the Software Heritage API which includes a limitation.
You could create authorized requests by setting `SWH_API_BEARER_TOKEN` environment variable with a token.


== Example usage

- SWHID with a bare core identifier: `include::swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`.

- SWHID with full contextual information: `include::swh:1:cnt:4c6ad635164b25b9bc2ebe17d2c3b7c0835f6035;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:7f5639fa3b68054ca0b062866dc62b22c3f11505;path=/README.md`.