Asciidoctor Deep Dive

You already have experience with Asciidoc and want to learn more? This talk shows you how to:

* use features to handle corner cases
* include source code and diagrams
* style a PDF
* add hyphenation
* get support from your IDE

For the demo parts you find a recording from 2018 here, a recording from 2019 is about to follow! https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive

Transcript

1. .consulting .solutions .partnership Asciidoctor Deep Dive Alexander Schwartz, Principal IT Consultant JavaZone Oslo – 11 September 2019
2. Asciidoctor Deep Dive © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 2 Motivation 1 Demo AsciiDoc Syntax and Ecosystem 2 Demo Asciidoctor PDF Generation 3 Summary 4
3. Asciidoctor Deep Dive © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 3 Motivation 1 Demo AsciiDoc Syntax and Ecosystem 2 Demo Asciidoctor PDF Generation 3 Summary 4
4. Motivation What do you use to write your docs? © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 4 Tool + – Office-Suite
5. Motivation What do you use to write your docs? © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 5 Tool + – Office-Suite Wiki
6. Motivation What to aim for in a Continuous Integration/Delivery setup © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 6 Code Snippets Publish result (to website) Printable Documentation Track Changes Search Documentation De-Duplication and Re-Use Text Code Fragments APIs Diagrams Tests Share Merge
7. Asciidoctor Offer © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 7 • Distraction free writing in an IDE • Expressive syntax to write documentation • Collaboration and versioning using Git • Utilize ecosystem • Use different inputs in your documentation pipeline • Create different outputs from the same sources https://asciidoctor.org/
8. Asciidoctor Deep Dive © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 8 Motivation 1 Demo AsciiDoc Syntax and Ecosystem 2 Demo Asciidoctor PDF Generation 3 Summary 4
9. Demo AsciiDoc and IDE support © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 9 Features: • Headers and Variables, Lists, References, Tables • Evaluation of Expressions • Listings, Math, Icons • PlantUML • Extensions • Spring REST Docs support
10. © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz Source: https://doctoolchain.github.io/docToolchain/ Building documentation tool chains with docToolchain 10
11. Building documentation tool chains with docToolchain © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 11 Source: https://doctoolchain.github.io/docToolchain/
12. Asciidoctor Deep Dive © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 12 Motivation 1 Demo AsciiDoc Syntax and Ecosystem 2 Demo Asciidoctor PDF Generation 3 Summary 4
13. Source: https://asciidoctor.org/docs/asciidoctor-pdf/ https://github.com/asciidoctor/asciidoctor-pdf/issues/20 https://github.com/ahus1/asciidoctor-deepdive/tree/master/manual Demo PDF Generation with Prawn/Asciidoctor PDF © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 13 • Defining a Template • Headers and Footers • Things to put on a Title • Pre-processing in Maven to add meta information • Using gem-maven-plugin as an alternative to standard Asciidoc Maven Plugin • Hyphenation as an example for Asciidoctor Runtime Patching
14. Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet Demo PDF Generation with Puppeteer/Asciidoctor PDF.js © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 14 • Reuse or define a Template • Style using CSS • Based on JavaScript, automate using yarn/npm • Allows custom layouts (for example multicolumn)
15. Asciidoctor Deep Dive © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 16 Motivation 1 Demo AsciiDoc Syntax and Ecosystem 2 Demo Asciidoctor PDF Generation 3 Summary 4
16. Personal Experiences © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 17 • Asciidoctor has a good user guide • Never needed to write passthrough-HTML for documentation • Asciidoctor PDF can theme it to your needs reasonably well, but has limitations for highly customized output. Try Asciidoctor PDF.js that supports full HMTL5 styling of the output • Something missing? Have look at the Asciidoctor Extension Lab!
17. Asciidoctor Offer © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 18 • Distraction free writing in an IDE • Expressive syntax to write documentation • Collaboration and versioning using Git • Utilize ecosystem • Use different inputs in your documentation pipeline • Create different outputs from the same sources https://asciidoctor.org/
18. Links © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 19 Asciidoctor https://asciidoctor.org Asciidoctor Extension Lab https://github.com/asciidoctor/asciidoctor-extensions-lab PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain https://doctoolchain.github.io/docToolchain/ @ahus1de Torquebox https://github.com/torquebox/jruby-maven-plugins Asciidoctor PDF.js https://github.com/Mogztter/asciidoctor-pdf.js Antora https://antora.org/ Video, Slides and Examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive
19. .consulting .solutions .partnership Alexander Schwartz Principal IT Consultant +49 171 5625767 alexander.schwartz@msg.group @ahus1de msg systems ag (Headquarters) Robert-Buerkle-Str. 1, 85737 Ismaning Germany www.msg.group