Asciidoctor

Asciidoctor is a text processor and toolchain as stated in their github pages. Under the term of text processor we can imagine a processor which gets on input a text annotated by in syntax and on output you get some readable format like pdf. The Asciidoctor works with AsciiDoc markup language.

There are multiple other markup languages which serves for writing text and providing their toolchain to provide text in well consumable/readable form. The text processor based on XML is DocBook, the well known for type setting is LaTeX. The html itself is a markup language where you put tags around your text and browser works as the processor to show the text formatted.

The advantage is that you can write the text annotate it with a formatting syntax and then with usage of the tools gets various output format - kind of html, pdf etc.

All the named markup languages have trouble that’s the syntax delay you when you’re writing and is harder to read the raw text with formatting markup.

That’s where AsciiDoc or maybe better known MarkDown languages and the Wiki Markup could be counted too. They are markup languages which aims to be easy to read and easy to write when working with raw text and still easily covertable to formats like html or pdf.

I fell in low with AsciiDoctor. I’m not sure why exactly in this one but but it seemed to me being a little more intuitive than MarkDown. I use on day to day basis, whenever I need to write some notes (especially more structured) or any kind of longer text.

I know that the first idea to look at it came from JBoss Community podcast JBoss Community Aylum on Asciidoctor which provides quite a good portion information what is it about and what is it good for.

Asciidoctor is based on syntax of old Python AsciDoc markup language but it rewrites the processor to Ruby and adds a many enhancements on top of it. It’s focused on writing documentation or technical type of text.

I learn to use Atom editor to write the text. There I use plugin to for syntax highligting (probably installed by default) and then plugin to preview the text written in AsciiDoctor markup. The shortcut CTRL+SHIFT+A started to be my beloved friend.

From writing text it was short way to use it for writing blog posts (see this blog and Hubpress.io platform) and using it for preparing presentation. It’s really my favorite way as I can restructuralize the text with ease that is not possible in GUI editors. I could use the pure Reveal.js but usage of AsciiDoc makes writing even easier.

Nevertheless all the time when I start to learn something I normally don’t like some small part of default behavior. Here it’s the fact that first paragraph after the title is presented as lead paragraph and it’s highlighted. I started to search and I get to understanding that each paragraph (block as formatable building block) gets a role by default. In this case it should be role lead which could be defined by hand in text by putting the role name into square brackets preceded by dot - like [.lead].

To disable the automatic lead paragraph styling, assign any role to the first paragraph.