Arbeiten mit Git und AsciiDoc:
Installation & Konfiguration

Ruby über den RubyInstaller, bspw. Ruby 3.x (x64), installieren. Eine minimale Installation ohne Devkit und ohne MSYS2 development toolchain reicht.

Asciidoctor und benötigte Tools per RubyGems über das Terminal installieren:

$ gem install asciidoctor
$ gem install asciidoctor-pdf
$ gem install rouge
$ gem install asciidoctor-diagram
$ gem install text-hyphen

Java OpenJDK über Adoptium oder Azul Zulu laden und installieren. Es ist egal ob die JDK oder JDK (LTS) Version genommen.

Graphviz über die Downloadseite laden und installieren:

Graphviz Dot fertig konfigurieren:

Ruby per Paketverwaltungssystem installieren, bspw. unter Ubuntu mit:

$ sudo apt-get install ruby

Asciidoctor und benötigte Tools per RubyGems über das Terminal installieren:

$ gem install asciidoctor
$ gem install asciidoctor-pdf
$ gem install rouge
$ gem install asciidoctor-diagram
$ gem install text-hyphen

Java OpenJDK über die Packetquellen oder über Adoptium oder Azul Zulu laden und installieren. Es ist egal ob die JDK oder JDK (LTS) Version genommen wird.

Für die lokale Generierung der Diagramme wird noch Graphviz benötigt und kann über die Packetquellen (Alternativ entsprechende Downloadseite) installiert werden:

$ sudo apt-get install graphviz

Homebrew nach zugehöriger Anleitung installieren.

Ruby per Homebrew über das Terminal installieren (alternative Anleitung):

% brew install ruby

Asciidoctor Tools per RubyGems über das Terminal installieren:

$ gem install asciidoctor
$ gem install asciidoctor-pdf
$ gem install rouge
$ gem install asciidoctor-diagram
$ gem install text-hyphen

Java OpenJDK über das Terminal installieren:

$ brew install openjdk

$ cd ~/Downloads
$ tar -xf openjdk-17.0.2_macos-aarch64_bin.tar.gz
$ sudo mv ~/Downloads/jdk-17.0.2.jdk /Library/Java/JavaVirtualMachines

Für die lokale Generierung der Diagramme wird noch Graphviz benötigt:

$ brew install graphviz

In das lokale Projektverzeichnis my-asciidoctor-project wechseln und Docker Container mit interaktiver Shell im Terminal (bspw. von VS Code) starten:

% cd my-asciidoctor-project/
% docker run -it -v "$(pwd):/documents/" asciidoctor/docker-asciidoctor  (1) (2)

% docker run -it -v "/path/to/my-asciidoctor-project/:/documents/" asciidoctor/docker-asciidoctor

Prüfen, ob lokaler Projektinhalt im Docker Container im /documents Verzeichnis verfügbar ist:

bash-5.1# pwd
/documents
bash-5.1# ls
document.adoc ...

Dokument mit Asciidoctor-Befehl im Docker Container als HTML/PDF erstellen:

bash-5.1# asciidoctor document.adoc
bash-5.1# asciidoctor-pdf document.adoc
bash-5.1# asciidoctor -r asciidoctor-diagram document.adoc
bash-5.1# asciidoctor-pdf -r asciidoctor-diagram document.adoc

Docker Container in der interaktiver Shell mit exit beenden:

bash-5.1# exit

Installation der VS Code Erweiterung: Remote - Containers

Projektverzeichnis über File  Open folder… in VS Code öffnen

Im geöffneten Projektverzeichnis wird ein Ordner .devcontainer mit den Dateien devcontainer.json und Dockerfile erstellt.

Folgenden Inhalte für die Datei devcontainer.json übernehmen:

{
    "name": "Asciidoctor", (1)
    "context": "..", (2)
    "dockerFile": "Dockerfile", (3)
    "extensions": [ (4)
        "asciidoctor.asciidoctor-vscode",
        "jebbs.plantuml"
    ],
    "settings": { (5)
        "asciidoc.asciidoctor_command": "asciidoctor -r asciidoctor-diagram",
        "asciidoc.preview.useEditorStyle": false,
        "asciidoc.use_asciidoctor_js": false
    }
}

Folgenden Inhalte für die Datei Dockerfile übernehmen:

FROM asciidoctor/docker-asciidoctor

In VS Code die View > Command Palette… öffnen und Remote-Containers: Reopen in Container auswählen.

Abbildung 2. Screenshot: Laufender Dev Container in VS Code

Beenden mit Rechtsklick auf Dev Container: Asciidoctor (links unten) …Close Remote Connection oder Reopen folder localy