Lock in $30 Savings on PRO—Offer Ends Soon! ⏳

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. 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
  2. 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
  3. Motivation What do you use to write your docs? ©

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

    msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 5 Tool + – Office-Suite Wiki
  5. 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
  6. 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/
  7. 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
  8. 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
  9. © msg | September 2019 | Asciidoctor Deep Dive |

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

    2019 | Asciidoctor Deep Dive | Alexander Schwartz 11 Source: https://doctoolchain.github.io/docToolchain/
  11. 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
  12. 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
  13. 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)
  14. 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
  15. 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!
  16. 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/
  17. 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
  18. .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