krimple / technical-docs-with-asciidoctor

A sample project that generates PDF and RevealJS content from asciidoc source and the asciidoctor toolset

Look, AsciiDoctor examples

Ken Rimple, March 2021

I’ve been through it all: using PowerPoint and Keynote, writing books in DocBook, attempts to get Pandoc and Markdown to write nice books and slides with LaTeX and Beamer, writing slides with HTML 5 and Reveal.js by hand, and then eventually I stumbled on Asciidoc and the Asciidoctor tool set.

Things I’m using in this barebones and silly set of tool examples:

• The Asciidoctor Docker image (it’s much harder to set up tooling on your own, take this and use it!)

• The asciidoctor-pdf tool for generating PDF output

• The asciidoctor-revealjs tool for generating slides in RevealJs

Note	I wanted to give a shout out to Dan Allen and the team working on AsciiDoctor. You make writing training content easier with your tools, and for that I thank you!

Building Docs and Slides

To generate the slide deck, use build-slides.sh, and to generate the book sample, use build-book.sh.

General project resources

• The Asciidoc language https://asciidoctor.org/docs/

• AsciiDoctor PDF https://asciidoctor.org/docs/asciidoctor-pdf/

• AsciiDoctor RevealJS https://docs.asciidoctor.org/reveal.js-converter/latest/

Warning

Asciidoctor’s RevealJs generator is touchy when it comes to the version of Reveal. Specifically it currently (as of March 2021) does not support Reveal 4.0 and above. See the details here: https://docs.asciidoctor.org/reveal.js-converter/latest/setup/compatibility-matrix/.

Running the Slide Show

cd reveal.js
npm install
npm start

Note	Browse to http://localhost:8000/slide-deck.html

These examples and Winders 10

If you are on Windows, consider installing WSL 2 and using Docker Engine with WSL Linux containers for a great command line experience, and install the Visual Studio Code WSL plugin. You’ll get a native Linux engine, docker integration, a bash shell, and the ability to run these samples. What’s not to like?

Otherwise, you probably will end up using the native Ruby installation on Windows, which takes a bit of time but is possible to use with some wrestling.