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

5f528a3f6814d28b583f31842e3e8d9e?s=128

Alexander Schwartz

September 11, 2019
Tweet

Transcript

  1. 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
  2. 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
  3. 4.

    Motivation What do you use to write your docs? ©

    msg | September 2019 | Asciidoctor Deep Dive | Alexander Schwartz 4 Tool + – Office-Suite
  4. 5.

    Motivation What do you use to write your docs? ©

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

    © msg | September 2019 | Asciidoctor Deep Dive |

    Alexander Schwartz Source: https://doctoolchain.github.io/docToolchain/ Building documentation tool chains with docToolchain 10
  10. 11.

    Building documentation tool chains with docToolchain © msg | September

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