= asciidoctor - Inclusione file da Gitea
Inclusione di file referenziati come URL Gitea
:authors: Celestino Amoroso
:docinfo: shared
:encoding: utf-8
:toc: right
:toclevels: 4
:toc-title: Indice Generale
:icons: font
:icon-set: fi
:numbered:
:table-caption: Tabella
:figure-caption: Diagramma
:docinfo1:
:sectlinks:
:sectanchors:
:source-highlighter: rouge
// :rouge-style: ThankfulEyes
:rouge-style: gruvbox
// :rouge-style: colorful
//:rouge-style: monokay

toc::[]

== Scopo
Questa guida spiega come includere in un documento Asciidoctor altri documenti che sono referenziati come URL Gitea. Ad esempio, 

  https://git.portale-stac.it/howto/linux/src/branch/main/SSH/README.adoc


=== Inclusione file in Asciidoctor

In generale, in un documento Asciidoctor l'inclusione di altri documenti si effettua con la direttiva `include::adoc-file-path-to-include[` _opzioni_ `]`.
Per ulteriori dettagli vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include/[qui].

L'opzione _leveloffset_ consente di specificare in quale livello della struttura del documento principale dev'essere inserito il documento esterno.
Ad esempio:

  inlcude::section-01.adoc[leveloffset=+1]

inserisce il documento importando le sue intestazioni con un livello più alto (interno) di quello in cui la direttiva `include::` è compresa (vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/[qui]).

==== Inclusione di documenti referenziati come URL
Oltre all'inclusione di file provenienti dal filesystem locale, Asciidoctor può incorporare file specificati tramite URL. Esempio.

  include::http://www.mysite.com/docs/section-01.adoc[leveloffset=+1]

==== Abilitazione inclusione URL
L'inclusione di documenti riferiti come URL è soggetta ad abilitazione esplicita (vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[qui]). L'abilitazione si esegue su riga di comando con l'attributo _-a allow-uri-read_.
Per includere URL quindi il comando `asciidoctor` dev'essere invocato come segue:

  asciidoctor -a allow-uri-read main.adoc

==== Abilitazione inclusione URL in Gitea
Per attivare l'inclusione delle URL in Gitea arricchire il valore di _RENDER_COMMAND_ aggiungendo l'attributo _allow-uri-read_:

.Sezione markup in gitea.ini
[source,ini]
----
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -s -a allow-uri-read -a 'newline=\n' -a lang=it -a showtitle --out-file=- -"
; Input is not a standard input but a file
IS_INPUT_FILE = false
----

Dopo la modifica, riavviare il servizio Gitea:

  sudo systemctl restart gitea

==== Inclusione di documenti contenuti in Gitea
Le URL che refenziano documenti Gitea devono puntare ai file originali, non a quelli processati. Ad esempio, l'URL

  https://git.portale-stac.it/howto/linux/src/branch/main/SSH/README.adoc

fa riferimento al file README.adoc contenuto nella directory SSH; il suo contenuto è preprocessato da Asciidoctor prima di essere ritornato al client/browser che lo richiede.
Tale contenuto è in formato HTML, non nella forma originale adoc.

Per ottenere il contenuto originale (raw) del file bisogna sostiuire nel path la componente *_src_*, posta fra il nome del repository (`howto/linux`) e la componente `branch` con la componente *_raw_*.
Nell'esempio di sopra, il link raw è:

  https://git.portale-stac.it/howto/linux/raw/branch/main/SSH/README.adoc