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

Asciidoctor Deep Dive

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

Alexander Schwartz

September 11, 2019
Tweet

More Decks by Alexander Schwartz

Other Decks in Technology

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
    [email protected]
    @ahus1de
    msg systems ag (Headquarters)
    Robert-Buerkle-Str. 1, 85737 Ismaning
    Germany
    www.msg.group

    View Slide