linux/Text/Markup/Asciidoctor/adoc_include_from_gitea.adoc

asciidoctor - Inclusione file da Gitea

Indice Generale

• 1. Scopo
  • 1.1. Inclusione file in Asciidoctor
    • 1.1.1. Inclusione di documenti referenziati come URL
    • 1.1.2. Abilitazione inclusione URL
    • 1.1.3. Abilitazione inclusione URL in Gitea
    • 1.1.4. Inclusione di documenti contenuti in Gitea

1. 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

1.1. 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 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 qui).

1.1.1. 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]

1.1.2. Abilitazione inclusione URL

L’inclusione di documenti riferiti come URL è soggetta ad abilitazione esplicita (vedere 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

1.1.3. 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

[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

1.1.4. 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