$30 off During Our Annual Pro Sale. View Details »

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