1. Einleitung

In diesem Tutorial wird gezeigt, wie mithilfe von Quarkus, Quarkus ROQ, AsciiDoc und GitHub Actions eine vollständige statische Dokumentationswebsite erstellt und automatisiert über GitHub Pages veröffentlicht werden kann.

Das Projekt eignet sich ideal für den Einsatz im schulischen oder professionellen Umfeld, etwa zur Veröffentlichung von

  • Tutorials

  • technischen Anleitungen

  • Unterrichtsmaterialien oder

  • Entwicklerdokumentationen

2. Technologien im Einsatz

🧱 Quarkus

Ein modernes Java-Framework für Cloud-native Anwendungen. In diesem Projekt dient es als schlanker Webserver – ideal für kleine statische Weblösungen.

🚀 ROQ Platform

ROQ erlaubt es uns einfache statische Webseiten, mithilfe von Quarkus zu erstellen. Hier wird der ROQ Web Starter verwendet, um mit wenigen Konfigurationsschritten ein funktionsfähiges Quarkus-Projekt aufzusetzen.

📝 AsciiDoc

Wird zur Erstellung technischer Dokumentationen verwendet. Im Gegensatz zu Markdown erlaubt AsciiDoc feinere Strukturierung und professionelle Formatierung – inklusive Inhaltsverzeichnis, Quellcode-Highlighting und Diagrammen. Die erstellten .adoc-Dateien lassen sich direkt, per Plugin, in HTML-Dateien konvertieren.

⚙️ GitHub Actions & Pages

GitHub Actions übernimmt den gesamten Build- und Deploy-Prozess im Hintergrund: Sobald Änderungen am Quelltext gepusht werden, wird automatisch eine neue HTML-Version erstellt und im gh-pages-Branch veröffentlicht. GitHub Pages stellt diese dann als statische Website öffentlich zur Verfügung – ganz ohne zusätzlichen Server.

3. Voraussetzungen

  • Java 21 installiert

  • Maven (bzw. Maven Wrapper ./mvnw)

  • Git & GitHub-Account

  • IDE oder Editor (z.B. IntelliJ, VS Code)

4. Projekt aufsetzen

a) Projekt erstellen

getting started

  • Klickt man auf Getting Started, gibt es ein Tutorial wo Schritt für Schritt erklärt wird, wie man ein Quarkus-Projekt erstellt, wo schon einige Fertigkeiten von ROQ dabei sind.

  • Erstelle ein neues Projekt (z.B. „roq-docs“)

  • Lade das Projekt als ZIP herunter und entpacke es

Oder man erstellt sich ein neues Projekt gleich im Terminal:

mvn io.quarkus.platform:quarkus-maven-plugin:3.2.1.Final:create \
    -DprojectGroupId=at.htlleonding \
    -DprojectArtifactId=quarkus-roq \
    -DclassName="com.example.GreetingResource" \
    -Dpath="/hello"

b) Repository initialisieren

git init
git remote add origin https://github.com/DEIN-NAME/roq-docs.git
git add .
git commit -m "Initial commit"
git push -u origin main

oder falls man schon ein vorhandenes Repo hat:

git clone https://github.com/DEIN-NAME/roq-docs.git

5. Projektstruktur

Projektstruktur

6. Wichtige Dateien & Klassen

In diesem Projekt gibt es nur wenige, aber sehr zentrale Dateien. Hier ein Überblick mit ausführlicher Erklärung:

pom.xml

Die zentrale Build-Konfigurationsdatei für das Projekt. Sie enthält u.a. das folgende AsciiDoctor Maven Plugin, das dafür sorgt, dass die index.adoc-Datei automatisch in eine HTML-Datei umgewandelt wird:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>2.2.1</version>
  <executions>
    <execution>
      <id>output-html</id>
      <phase>prepare-package</phase> (1)
      <goals>
        <goal>process-asciidoc</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <backend>html</backend>
    <sourceDirectory>src/main/asciidoc</sourceDirectory> (2)
    <outputDirectory>${project.build.directory}/generated-docs</outputDirectory> (3)
  </configuration>
</plugin>
1 Sorgt dafür, dass die AsciiDoc-Dateien vor dem Verpacken des Projekts zu HTML konvertiert werden.
2 Hier liegen die erstellten .adoc-Dateien.
3 Der Zielordner, in dem die HTML-Dateien abgelegt werden – wird später auf GitHub Pages deployed.

index.adoc

Diese Datei enthält die gesamte Dokumentation und wird per Maven-Plugin zu HTML konvertiert.

Aus dem:

= Mein Tutorial
:toc:
...

wird eine vollständige, statische HTML-Seite.

.github/workflows/deployment.yml

Der Github-Workflow sorgt dafür, dass bei jedem Push auf den main-Branch die Website neu generiert und automatisch auf GitHub Pages veröffentlicht wird.

Wichtige Zeile:

- name: Deploy to GitHub Pages
  uses: JamesIves/github-pages-deploy-action@v4
  with:
    branch: gh-pages (1)
    folder: target/generated-docs

Das bedeutet:

1 Der Ordner target/generated-docs mit der HTML-Seite wird in den Branch gh-pages kopiert.

GitHub Pages zeigt diesen Branch automatisch als Website an.

8. Was passiert im Hintergrund?

Projekt-Workflow

  1. Man schreibt das Tutorial oder die Dokumentation in index.adoc

  2. Beim Push auf main wird der GitHub Actions Workflow automatisch ausgelöst

  3. Der Workflow führt ./mvnw package aus → daraus entsteht eine HTML-Version der Doku

  4. Das HTML-File landet im Ordner target/generated-docs

  5. Der Workflow kopiert diesen Ordner in den Branch gh-pages

  6. GitHub Pages zeigt den Inhalt des Branches als Webseite

9. Projekt starten (lokal)

./mvnw clean package     # HTML-File generieren
./mvnw quarkus:dev       # Lokal starten

Dann im Browser öffnen:

http://localhost:8080

Wenn hier alles funktioniert, ist die Adoc-Datei korrekt zu einer HTML-Datei generiert worden. Nun können wir anfangen zu deployen.

10. GitHub Pages einrichten

  • GitHub-Repo → Settings → Pages

GitHub Pages aktivieren
settings
enable

Wenn man die Schritte befolgt wie auf den Bildern, wird der Link zur Webseite direkt im GH-Repo angezeigt und man muss ihn nicht immer selber eingeben, sondern kann direkt im Repo draufklicken.

11. Visualisierung des Deploy-Workflows

GitHub Actions Workflow

12. Fazit

Mit Quarkus ROQ und GitHub Pages ist es einfach, eine statische Website zu erstellen und zu hosten. Vor allem, wenn man gut mit AsciiDoc umgehen kann, ist es ein sehr mächtiges Tool in Kombination mit allen anderen Technologien die verwendet wurden.