Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Doku-Microsites mit jBake

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.

Ralf D. Müller

March 16, 2021
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

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?
  40. None
  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
  45. None