Doku-Microsites mit jBake

Dokumentation in Markdown oder AsciiDoc zu erstellen ist einfach. GitHub, GitLab und Bitbucket zeigen die Dokumente schon gleich im Repository als HTML-Seite an. Doch wie bekomme ich aus diesen Dokumenten jetzt eine schicke Website hin, die nicht nur das Projekt dokumentiert, sondern auch das Projekt über eine nette Landingpage vorstellt, die Architektur bereitstellt und einen Newsfeed anbietet?

In diesem Vortrag zeige ich, warum sich jBake gerade für Java-Projekte ausgezeichnet eignet um für jedes Projekte mit wenig Aufwand eine schicke Microsite zu erstellen - vom Plain-Text-Dokument bis zur veröffentlichten Website mit TLS.

Dabei werde ich viele Tricks und Kniffe aus dem Projektalltag einfliessen lassen. Landingpage, Architekturdokumentation mit arc42, Anwenderdoku mit AsciiDoc, Blog mit RSS-Feed und eine Suche werden kombiniert und einfach in das bestehende Projekt-Repository entsprechend dem Docs-as-Code-Ansatz integriert. Über ein Open Source Template wird er Einstieg in die Erstellung einer eigenen Microsite nach dem Vortrag erleichtert.

Transcript

1. Doku-Microsites mit jBake Ein Erfahrungsbericht in drei Akten 16.03.2021 | Ralf D. Müller | JavaLand
2. I. Akt „use the Force, Luke!“ Das richtige Werkzeug DB Systel GmbH | Ralf D. Müller | @RalfDMueller 2
3. Grundlage: Docs-as-Code DB Systel GmbH | Ralf D. Müller | @RalfDMueller 3 .adoc .adoc txt Fork PR txt Build- Server On Change .html Publish
4. Markdown Toller Standard für einfache Auszeichnungen Features Span Elements Links Emphasis Code Images Block Elements Paragraphs and Line Breaks Headers Blockquotes Lists Code Blocks Horizontal Rules TOC Tables (Feature Rich) Includes (Level-Offset) PlantUML Admonitions Attributes Anchors Footnotes, Index, Glossary Videos Syntax Highlighting Callouts Math Rendering Outputformats DB Systel GmbH | Ralf D. Müller | @RalfDMueller 4
5. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? •CommonMark •CriticMarkup •Discount •DocFX •ExtraMark •Ghost's Markdown/Haunted Markdown •GitHub Flavored Markdown •GitLab Flavored Markdown (with login) •Haroopad Flavored Markdown •iA Writer's Markdown •Kramdown •Leanpub Flavored Markdown •Litedown •Lunamark •Madoko •Markdown •Markdown 2 •Markdown Extra •Markdown-it •Markua •Maruku •MultiMarkdown •Pandoc's Markdown •PHP Markdown Extra Extended •Python Markdown •R Markdown •Redcarpet •Remarkable •Rhythmus •Scholarly Markdown •Showdown •StackOverflow's Markdown •Taiga Markdown •Trello's Markdown •vfmd •Xcode/Swift Playgrounds Markup https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors DB Systel GmbH | Ralf D. Müller | @RalfDMueller 5
6. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? Funktioniert dann unsere Toolchain noch? Haben wir ein Editor-Preview? DB Systel GmbH | Ralf D. Müller | @RalfDMueller 6 •CommonMark •CriticMarkup •Discount •DocFX •ExtraMark •Ghost's Markdown/Haunted Markdown •GitHub Flavored Markdown •GitLab Flavored Markdown (with login) •Haroopad Flavored Markdown •iA Writer's Markdown •Kramdown •Leanpub Flavored Markdown •Litedown •Lunamark •Madoko •Markdown •Markdown 2 •Markdown Extra •Markdown-it •Markua •Maruku •MultiMarkdown •Pandoc's Markdown •PHP Markdown Extra Extended •Python Markdown •R Markdown •Redcarpet •Remarkable •Rhythmus •Scholarly Markdown •Showdown •StackOverflow's Markdown •Taiga Markdown •Trello's Markdown •vfmd •Xcode/Swift Playgrounds Markup
7. Beispiel: Admonitions DB Systel GmbH | Ralf D. Müller | @RalfDMueller 7
8. DB Systel GmbH | Ralf D. Müller | @RalfDMueller 8 :::note The content and title *can* include markdown. ::: :::tip You can specify an optional title Heads up! Here's a pro-tip. ::: :::info Useful information. ::: :::caution Warning! You better pay attention! ::: :::danger Danger danger, mayday! ::: ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning ::: ::: details This is a details block, which does not work in IE / Edge ::: https://v1.vuepress.vuejs.org/guide/markdown.html#custom-containers https://v2.docusaurus.io/docs/2.0.0-alpha.70/markdown-features > [!NOTE] > Information the user should > notice even if skimming. > [!TIP] > Optional information to help > a user be more successful. > [!IMPORTANT] > Essential information required > for user success. > [!CAUTION] > Negative potential consequences > of an action. > [!WARNING] > Dangerous certain consequences > of an action. https://docs.microsoft.com/de-de/contribute/markdown-reference
9. AsciiDoc / Asciidoctor leistungsfähige Syntax für technische Dokumentation in Ruby geschrieben mit jRuby auf der JVM gewrapped mit Opal nach JavaScript transpiliert => Keine Dialekte! DB Systel GmbH | Ralf D. Müller | @RalfDMueller 9
10. Ende I. Akt „use AsciiDoc, Duke!“ Das richtige Werkzeug AsciiDoc mit Asciidoctor DB Systel GmbH | Ralf D. Müller | @RalfDMueller 10
11. II. Akt DB Systel GmbH | Ralf D. Müller | @RalfDMueller 11 https://pixabay.com/de/photos/bruce-lee-hong-kong-2167350/
12. II. Akt Wie Bruce Lee dem Gegner ausweichen Keine neuen Baustellen eröffnen DB Systel GmbH | Ralf D. Müller | @RalfDMueller 12 https://pixabay.com/de/photos/bruce-lee-hong-kong-2167350/
13. Static Site Generators DB Systel GmbH | Ralf D. Müller | @RalfDMueller 13 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche
14. Als Microsite (bzw. Mikro-Website) bezeichnet man im Webdesign eine schlanke Website mit wenigen Unterseiten und geringer Navigationstiefe innerhalb eines größeren Internet-Auftritts. Die Microsites sind optisch von der eigentlichen Website unabhängig und bilden thematisch und gestalterisch eine eigenständige kleine Internetpräsenz. https://de.wikipedia.org/wiki/Microsite DB Systel GmbH | Ralf D. Müller | @RalfDMueller 14
15. Static Site Generators https://jamstack.org/generators/ gelistete Static Site Generatoren! 322 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 15
16. Static Site Generators ? ? ? ? ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ ? DB Systel GmbH | Ralf D. Müller | @RalfDMueller 16
17. Static Site Generators ? ? ? ? ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ DB Systel GmbH | Ralf D. Müller | @RalfDMueller 17
18. ? ? Static Site Generators ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ ? DB Systel GmbH | Ralf D. Müller | @RalfDMueller 18
19. Static Site Generators ? ? ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ DB Systel GmbH | Ralf D. Müller | @RalfDMueller 19
20. ? Static Site Generators ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ DB Systel GmbH | Ralf D. Müller | @RalfDMueller 20
21. Static Site Generators ? gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ DB Systel GmbH | Ralf D. Müller | @RalfDMueller 21
22. Static Site Generators gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ DB Systel GmbH | Ralf D. Müller | @RalfDMueller 22
23. Static Site Generators gelistete Static Site Generatoren! 322 unterstützen AsciiDoc ca 6 https://jamstack.org/generators/ unterstützen Java 2 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 23
24. Static Site Generators: jBake Geschrieben in Java Verfügbar als Library und CLI Plugins für Maven, Gradle, mill, sbt und SBuild verfügbar Installierbar z.B. über sdkman und Homebrew Freemarker, Thymeleaf, Jade und Groovy Template Unterstützung HTML, MarkDown und AsciiDoc als Markup Twitter Bootstrap out of the box DB Systel GmbH | Ralf D. Müller | @RalfDMueller 24
25. Jbake –i –t groovy Freemarker, Thymeleaf, Jade und Groovy Template Unterstützung DB Systel GmbH | Ralf D. Müller | @RalfDMueller 25 <h2>${page.title}</h1> <% if (page.title.startsWith("ADR")) { %> <span class="authors"> ${page.authors.join(", ")} </span> <% } %> <%include "footer.gsp" %> "footer.gsp"
26. Struktur DB Systel GmbH | Ralf D. Müller | @RalfDMueller 26 |-- assets | |-- favicon.gif | |-- robots.txt | |-- img | | |-- logo.png | |-- js | | |-- custom.js | |-- css | |-- style.css | |-- content | |-- about.adoc | |-- 2013 | |-- 01 | | |-- hello-world.adoc | |-- 02 | |-- weekly-links-1.adoc | |-- weekly-links-2.md | | |-- templates | |-- footer.gsp | |-- header.gsp | |-- index.gsp | |-- menu.gsp | |-- page.gsp | |-- post.gsp | |-- feed.gsp | |-- jbake.properties
27. Jbake –b –s DB Systel GmbH | Ralf D. Müller | @RalfDMueller 27
28. Templates & Themes Für Jekyll, Hugo etc. gibt es Themes als Download … und für jBake? DB Systel GmbH | Ralf D. Müller | @RalfDMueller 28
29. Landing-Page DB Systel GmbH | Ralf D. Müller | @RalfDMueller 29
30. Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | Ralf D. Müller | @RalfDMueller 30
31. News / Blog mit RSS-Feed DB Systel GmbH | Ralf D. Müller | @RalfDMueller 31
32. Default Template - Menu DB Systel GmbH | Ralf D. Müller | @RalfDMueller 32 … <div class="navbar-collapse collapse"> <ul class="nav navbar-nav"> <li><a href="<%if (content.rootpath) {%>${content.rootpath}<% } else { %><% }%>index.html">Home</a></li> <li><a href="<%if (content.rootpath) {%>${content.rootpath}<% } else { %><% }%>about.html">About</a></li> <li><a href="<%if (content.rootpath) {%>${content.rootpath}<% } else { %><% }%>${config.feed_file}">Subscribe</a></li> <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a> <ul class="dropdown-menu"> <li><a href="#">Action</a></li> <li><a href="#">Another action</a></li> <li><a href="#">Something else here</a></li> <li class="divider"></li> <li class="dropdown-header">Nav header</li> <li><a href="#">Separated link</a></li> <li><a href="#">One more separated link</a></li> </ul> </li> </ul> </div><!--/.nav-collapse --> …
33. Ende II. Akt Wie Bruce Lee dem Gegner ausweichen Keine neuen Baustellen eröffnen – bekanntes Wissen einsetzen: Java, GSP, Bootstrap DB Systel GmbH | Ralf D. Müller | @RalfDMueller 33 https://pixabay.com/de/photos/bruce-lee-hong-kong-2167350/
34. III. Akt Sei wie John Carmack “Focus is a matter of deciding what things you’re not going to do.” DB Systel GmbH | Ralf D. Müller | @RalfDMueller 34 https://twitter.com/Sundown_Ageha/status/1243357719886610433/photo/1
35. Struktur DB Systel GmbH | Ralf D. Müller | @RalfDMueller 35 |-- assets | |-- favicon.gif | |-- robots.txt | |-- img | | |-- logo.png | |-- js | | |-- custom.js | |-- css | |-- style.css | |-- content | |-- about.adoc | |-- 2013 | |-- 01 | | |-- hello-world.adoc | |-- 02 | |-- weekly-links-1.adoc | |-- weekly-links-2.md | | |-- templates | |-- footer.gsp | |-- header.gsp | |-- index.gsp | |-- menu.gsp | |-- page.gsp | |-- post.gsp | |-- feed.gsp | |-- jbake.properties
36. Externalize the Theme DB Systel GmbH | Ralf D. Müller | @RalfDMueller 36 Theme
37. Add arc42 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 37
38. Add arc42 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 38 docToolchain
39. arc42 Speed-Run DB Systel GmbH | Ralf D. Müller | @RalfDMueller 39 Wie schnell kann eine arc42-Template Microsite aufgesetzt werden?
41. Ende III. Akt Sei wie John Carmack “Focus is a matter of deciding what things you’re not going to do.” Boiler-Plate raus, Content rein DB Systel GmbH | Ralf D. Müller | @RalfDMueller 41 https://twitter.com/Sundown_Ageha/status/1243357719886610433/photo/1
42. Epilog DB Systel GmbH | Ralf D. Müller | @RalfDMueller 42
43. Epilog DB Systel GmbH | Ralf D. Müller | @RalfDMueller 43 I. Benutze AsciiDoc für technische Dokumentation jBake II. Nutze das, was funzt mit Technologien, die Du kennst III. Lass andere das Setup erstellen und konzentriere Dich auf das Wesentliche docToolchain
44. Danke für Eure Aufmerksamkeit! Thanx to all Contributors and Sponsors! jBake docToolchain