AsciiDoc ist eine vereinfachte Auszeichnungssprache, die dazu dient, Texte in verschiedenen Dokumentenformaten zu veröffentlichen. AsciiDoc-Dateien können entweder nach HTML oder ins DocBook-Format konvertiert werden – und von dort dann ggf. weiter in viele andere Formate, z. B. PDF oder Manpage.

Quelle: wikipedia.org

Homepage: asciidoc.org

Mit der Hilfe von Asciidoc lassen sich sich, ähnlich wie bei markdown lassen sich damit recht einfach gut formatierte Dokumente erstellen.

Installation

Man sollte prüfen ob in den Repos des entsprechenden Systems die Pakete asciidoc und asciidoctor vorhanden sind. Falls dies nicht der Fall ist so kann man sich Asciidoc noch auf anderen Wegen installieren, wie das geht erfährt man hier: asciidoc.org

Bei meiner Demo verwende ich NixOS und starte dort eine nix-shell, welche dann die entsprechenden Pakete enthält.

[rasputin@nixos:~]$ nix-shell -p asciidoc-full-with-plugins asciidoctor
[nix-shell:~]$ asciidoctor -V
Asciidoctor 1.5.7.1 [https://asciidoctor.org]
Runtime Environment (ruby 2.5.5p157 (2019-03-15) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

Praktischerweise bietet mir NixOS hierbei gleich eine Installation mit allen relevanten Plugins an.

Verwendung von Asciidoc

Ein AsciiDoc cheatsheet findet man hier: AsciiDoc cheatsheet

Für meine Demo lege ich eine einfache Datei namens asciidoc_test.adoc an, welche den folgenden Inhalt hat:

:icons: font
== techgoat.net
WARNING: Test
[source]
`$Lorem Ipsum!`

TIP: techgoat.net

NOTE: Hier könnte deine Notiz stehen!

Um aus dieser einfachen Textdatei eine pdf Datei zu erstellen verwendet man den Befehl asciidoctor-pdf <Dateiname> und Asciidoc erstellt daraus dann die <dateiname>.pdf.

Somit erstellen wir nun mit dem Befehl asciidoctor-pdf asciidoc_test.adoc die Datei asciidoc_test.pdf, welche wie folgt aussieht:

bei jedem speichern automatisch die pdf Datei erstellen

In Vim hat man per autocmd die Möglichkeit bei jedem speichern einer *.adoc Datei mit Hilfe des asciidoctor-pdf Befehls eine entsprechende pdf Datei zu erstellen.

autocmd BufWritePost *.adoc :silent !asciidoctor-pdf *.adoc

Diesen Befehl kann man entweder live in Vim oder in der entsprechenden .vimrc eintragen.

Dieser Befehl führt nach dem schreiben der Datei den Befehl asciidoctor-pdf *.adoc aus und der Parameter :silent entfernt das finale drücken der Enter Taste nach Durchführung des Befehls.

Hinweis:
Man kann auch mehrere Befehle mit z.B. && verbinden.

Beispiel:
autocmd BufWritePost *.adoc :silent !asciidoctor-pdf *.adoc && bash gitpush.sh

Somit kann man beispielsweise seine Dokumente immer mit der entsprechenden .pdf Datei in git ablegen.