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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

4. Motivation
   What do you use to write your docs?
   © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 4
   Tool + –
   Office-Suite
   

   View Slide

5. Motivation
   What do you use to write your docs?
   © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 5
   Tool + –
   Office-Suite
   Wiki
   

   View Slide

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
   

   View Slide

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/
   

   View Slide

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
   

   View Slide

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
   

   View Slide

10. © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz Source: https://doctoolchain.github.io/docToolchain/
    Building documentation tool chains with docToolchain
    10
    

    View Slide

11. Building documentation tool chains with docToolchain
    © msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 11
    Source: https://doctoolchain.github.io/docToolchain/
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

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!
    

    View Slide

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/
    

    View Slide

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
    

    View Slide

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
    

    View Slide