Tweet
Tweet

Slide 1

Slide 1 text

Doku-Microsites mit jBake Ein Erfahrungsbericht in drei Akten 16.03.2021 | Ralf D. Müller | JavaLand

Slide 2

Slide 2 text

I. Akt „use the Force, Luke!“ Das richtige Werkzeug DB Systel GmbH | Ralf D. Müller | @RalfDMueller 2

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Beispiel: Admonitions DB Systel GmbH | Ralf D. Müller | @RalfDMueller 7

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Ende I. Akt „use AsciiDoc, Duke!“ Das richtige Werkzeug AsciiDoc mit Asciidoctor DB Systel GmbH | Ralf D. Müller | @RalfDMueller 10

Slide 11

Slide 11 text

II. Akt DB Systel GmbH | Ralf D. Müller | @RalfDMueller 11 https://pixabay.com/de/photos/bruce-lee-hong-kong-2167350/

Slide 12

Slide 12 text

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/

Slide 13

Slide 13 text

Static Site Generators DB Systel GmbH | Ralf D. Müller | @RalfDMueller 13 arc42 Dokumentation Test-Reports Landing-Page Blog User-Manual Suche

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

Static Site Generators https://jamstack.org/generators/ gelistete Static Site Generatoren! 322 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 15

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

? ? 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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

? 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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Jbake –i –t groovy Freemarker, Thymeleaf, Jade und Groovy Template Unterstützung DB Systel GmbH | Ralf D. Müller | @RalfDMueller 25

${page.title} <% if (page.title.startsWith("ADR")) { %> ${page.authors.join(", ")} <% } %> <%include "footer.gsp" %> "footer.gsp"

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Jbake –b –s DB Systel GmbH | Ralf D. Müller | @RalfDMueller 27

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

Landing-Page DB Systel GmbH | Ralf D. Müller | @RalfDMueller 29

Slide 30

Slide 30 text

Umfangreiche AsciiDoc-Dokumentation DB Systel GmbH | Ralf D. Müller | @RalfDMueller 30

Slide 31

Slide 31 text

News / Blog mit RSS-Feed DB Systel GmbH | Ralf D. Müller | @RalfDMueller 31

Slide 32

Slide 32 text

Default Template - Menu DB Systel GmbH | Ralf D. Müller | @RalfDMueller 32 …
  • Home
  • About
  • Subscribe
  • Dropdown
    • Action
    • Another action
    • Something else here
    • Nav header
    • Separated link
    • One more separated link
…

Slide 33

Slide 33 text

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/

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

Externalize the Theme DB Systel GmbH | Ralf D. Müller | @RalfDMueller 36 Theme

Slide 37

Slide 37 text

Add arc42 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 37

Slide 38

Slide 38 text

Add arc42 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 38 docToolchain

Slide 39

Slide 39 text

arc42 Speed-Run DB Systel GmbH | Ralf D. Müller | @RalfDMueller 39 Wie schnell kann eine arc42-Template Microsite aufgesetzt werden?

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

Epilog DB Systel GmbH | Ralf D. Müller | @RalfDMueller 42

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

Danke für Eure Aufmerksamkeit! Thanx to all Contributors and Sponsors! jBake docToolchain

Slide 45

Slide 45 text

No content