Docs as Code kann PDF

Ein kleines, sofort einsetzbares Plugin für die integrierte Entwicklungsumgebung (IDE) macht es möglich: Nutzen Sie die Vorteile von AsciiDoc ganz komfortabel, ohne alle Auszeichnungselemente im Kopf haben zu müssen! In dieser Veranstaltung erleben Sie, wie eine solche Erweiterung den Einstieg in „Docs as Code“ erheblich erleichtert und die tägliche Arbeit durch einen Schnellzugriff auf häufige Elemente und direkte Vorschaufunktionen vereinfacht.

Immer mehr Redaktionsteams entscheiden sich bewusst für AsciiDoc, denn die Sprache wurde mit den Bedürfnissen der Technischen Dokumentation im Hinterkopf entwickelt. Sie bietet wertvolle Funktionen wie zum Beispiel Attribute zur zentralen Verwaltung von Inhalten, flexible Querverweise oder die Möglichkeit Code-Beispiele nicht nur einzubetten sondern darin auch bestimmte Stellen optisch hervorzuheben.

Auch wenn Sie auf die zuverlässige Ausgabe einer PDF-Datei angewiesen sind, ist AsciiDoc für Sie ein geeigneter Ansatz. Die Werkzeuge rund um AsciiDoc ermöglichen neben der Erstellung von modernen HTML5-Webseiten auch die mühelose Generierung von PDF-Dokumenten – neben weiteren Formaten wie DocBook oder EPUB.

Transcript

1. Docs as Code kann PDF Alexander Schwartz, Principal Software Engineer @ IBM tekom (online) | 2026-09-21
2. Docs as Code kann PDF 1 Aus Text ein PDF erstellen 2 AsciiDoc: Sprache, Konverter und Werkzeuge 3 Funktionsüberblick mit Demo 4 Das Wichtigste im Überblick CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 2
3. AsciiDoc Deep Dive 1 Aus Text ein PDF erstellen 2 AsciiDoc: Sprache, Konverter und Werkzeuge 3 Funktionsüberblick mit Demo 4 Das Wichtigste im Überblick CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 3
4. Aus Text ein PDF erstellen Aus Text ein PDF erstellen == Chapter === Sub-Chapter The Asciidoctor project is an effort to bring a comprehensive and accessible publishing toolchain, centered around the AsciiDoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM. ... |=== | Col1 |Col2 |Col3 | Col4 | There are incomprehensible, sometimes long but ubiquitous words with hyphenation. | There are incomprehensible, ... CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 4
5. Aus Text ein PDF erstellen Seitenlayout definieren extends: default page: background_color: ffffff layout: portait margin: [1.3in, 0.72in, 0.8in, 0.72in] size: A4 base: align: justify font_color: 000000 link: font_color: 428bca literal: font_color: b12146 font_family: M+ 1mn header: border_color: dddddd border_width: 0.25 height: 1.1in image_vertical_align: bottom recto: right: content: image:header.svg[fit=scale-down] center: content: '{chapter-title}' verso: CC BY-NC-SAright: 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz content: $header_recto_right_content 5
6. Aus Text ein PDF erstellen AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung AsciiDoc® • Fokussiertes Schreiben ohne Ablenkung • Hat alles, was technische Dokumentation benötigt • Existiert seit 2002 • Standardisierung in 2020 bei Eclipse Foundation gestartet Asciidoctor • Erzeugt aus AsciiDoc Dateien HTML, PDFs, EPUB, Docbook, .. • OpenSource Implementierung • Läuft mit Java, Ruby und JavaScript • Kann z. B. in Maven und Gradle Builds über Plugins integriert werden CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz https://asciidoc-wg.eclipse.org/ Asciidoctor https://asciidoctor.org/ 6
7. Asciidoctor Deep Dive 1 Aus Text ein PDF erstellen 2 AsciiDoc: Sprache, Konverter und Werkzeuge 3 Funktionsüberblick mit Demo 4 Das Wichtigste im Überblick CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 7
8. AsciiDoc: Sprache, Konverter und Werkzeuge Texte und Listen Each sentence should be in a separate line. Every blank line creates a new paragraph. You can write *bold* text. _Italic_ works as well text. Lists . work . with . dots to make them numbered and * asterisks * to * make bullet points. CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 8
9. AsciiDoc: Sprache, Konverter und Werkzeuge Abschnitte und Auszeichnungen [IMPORTANT] -You can mark a paragraph to be important. -TIP: There is also the shorter one-linesyntax. ==== This is an example block. Use it to provide examples to your users. ==== ---This is a listing. You can provide syntax highlighting for XML/Java etc. here. ---- CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 9
10. AsciiDoc: Sprache, Konverter und Werkzeuge Tabellen Tables are blocks, `|===` marks their beginning and end. .Table title [cols="1,1,3a,1"] |=== |H1 |H2 |H3 |H4 |Cell 1 |Cell 2 |Formatting *of words* works like in _before_ if you switch the column or cell to AsciiDoc format. |Cell 4 |=== CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 10
11. AsciiDoc: Sprache, Konverter und Werkzeuge Bilder Images can be in-line and as blocks. An image:file.svg[pdfwidth=3cm] image inline. An image with a caption: .This is an image image::file.svg[] For schematic drawings prefer to use SVG images for best results on the Web and in PDFs. CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 11
12. AsciiDoc: Sprache, Konverter und Werkzeuge Grafiken am Beispiel PlantUML To store diagrams as text, have a look at PlantUML: .Diagrams can have a caption as well. plantuml::showcase_swimlanes.puml[swimlanes,svg] @startuml skinparam shadowing false |Component with Web-UI| start :User opens web page; :Forward to authentication; |#AntiqueWhite|Authentication| :Authenticate with user name\nand password; :Forward to Web-UI; |Component with Web-UI| :Open Web-UI; stop @enduml CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 12
13. AsciiDoc: Sprache, Konverter und Werkzeuge Quellcode-Beispiele einbinden .Standard include [source,java] ---include::Example.java[] ---- :icons: font .Pick a block with callout [source,java,indent=0] ---include::Example.java[tag=sop] ---<1> this is your first line of Java CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 13
14. AsciiDoc: Sprache, Konverter und Werkzeuge Technische Dokumentation als Teil des Entwicklungsprozesses • Dokumente ohne Ablenkung in der Entwicklungsumgebung schreiben • Kollaboration und Versionierung mit Git • Rechtschreib- und Grammatikprüfung • Syntax-Highlighting • Preview Liste der Editoren: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/ CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 14
15. Asciidoctor Deep Dive 1 Aus Text ein PDF erstellen 2 AsciiDoc: Sprache, Konverter und Werkzeuge 3 Funktionsüberblick mit Demo 4 Das Wichtigste im Überblick CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 15
16. Funktionsüberblick mit Demo Demo PDF Erstellung mit Prawn/Asciidoctor PDF • • • • • • Template auswählen Kopf- und Fußzeile konfigurieren Titelseite definieren Übergabe von Attributen z. B. via Maven Silbentrennung Formelsatz nur mit zusätzlichen Erweiterungen Source: https://asciidoctor.org/docs/asciidoctor-pdf/ https://github.com/asciidoctor/asciidoctor-pdf/issues/20 https://github.com/ahus1/asciidoctor-deepdive/tree/master/manual CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 16
17. Funktionsüberblick mit Demo Demo PDF Erstellung mit Vivliostyle/Asciidoctor Web PDF • • • • Bestehende Templates vs. individuelle Templates Design mittels CSS Basiert auf JavaScript, automatisierbar mit yarn/npm Individuelle Layouts Source: https://github.com/ggrossetie/asciidoctor-web-pdf/tree/main/examples/cheat-sheet CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 17
18. Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 18
19. Asciidoctor Deep Dive 1 Aus Text ein PDF erstellen 2 Demo AsciiDoc Syntax und Ökosystem 3 Funktionsüberblick mit Demo 4 Das Wichtigste im Überblick CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 19
20. Das Wichtigste im Überblick AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung AsciiDoc® • Fokussiertes Schreiben ohne Ablenkung • Hat alles, was technische Dokumentation benötigt • Existiert seit 2002 • Standardisierung in 2020 bei Eclipse Foundation gestartet Asciidoctor • Erzeugt aus AsciiDoc Dateien HTML, PDFs, EPUB, Docbook, .. • OpenSource Implementierung • Läuft mit Java, Ruby und JavaScript • Kann z. B. in Maven und Gradle Builds über Plugins integriert werden CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz https://asciidoc-wg.eclipse.org/ Asciidoctor https://asciidoctor.org/ 20
21. Das Wichtigste im Überblick Projektfragen auf dem Weg zu Docs as Code für PDFs • Welche Ausdrucksmöglichkeiten brauche ich für meine Inhalte? Sind die Möglichkeiten von AsciiDoc die richtigen? • Möchte ein PDF-Template parametrisieren, oder komplett frei gestalten? Template -> asciidoctor-pdf CSS -> asciidoctor-web-pdf • Unterstützt der Konverter alle Ausdrucksmöglichkeiten, die ich benötige? Proof of concept erstellen, beide Ergebnisse vergleichen. • Welche Werkzeuge nutze ich zum Schreiben? IntelliJ IDEA, VSCode, … • Wie automatisiere ich meine Pipeline? Asciidoctor hat die passenden Werkzeuge: Kommandozeile oder Docker-Container CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 21
22. Das Wichtigste im Überblick Links AsciiDoc https://asciidoc.org Asciidoctor PDF https://docs.asciidoctor.org/pdf-converter/latest/ Asciidoctor https://asciidoctor.org Asciidoctor Web PDF https://github.com/ggrossetie/asciidoctor-web-pdf IntelliJ AsciiDoc Plugin Documentation as Code mit Asciidoctor https://ahus1.de/post/technical-writing-udemy https://heise.de/-4642013 PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain https://doctoolchain.github.io/docToolchain/ CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz Docker Container mit Asciidoctor & Co. https://github.com/asciidoctor/docker-asciidoctor/ @ahus1@fosstodon.org @ahus1de 22
23. Kontakt Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | September 2026 | Docs as Code kann PDF | Alexander Schwartz 23