Asciidoctor

Awesome Asciidoctor: Exclude Parts From Included Files

Posted on by  
Hubert Klein Ikkink

In a previous post we learned how to include parts of a document in the generated output. The included parts are defined using tags. The start of a tag is defined in a comment with the format tag::_tagName_[] and the end has the format end::_tagName_[]. Next we must use the tags attribute for the include macro followed by the tagName. If we don’t want to include a tag we must prefix it with an exclamation mark (!).

Continue reading →

Awesome Asciidoctor: Document Attributes With Styling

Posted on by  
Hubert Klein Ikkink

Document attributes in Asciidoctor are very powerful. We can assign values to a document attributes and reference the attribute name in our document enclosed between curly braces. Asciidoctor will fill in the value when the document is transformed. Instead of a plain value we can also use styling markup in the document attribute definition. We must use the passthrough macro and allow for quote substitution.

Continue reading →

Awesome Asciidoctor: Use Diagram Block Macro To Include Diagrams

Posted on by  
Hubert Klein Ikkink

With the Asciidoctor diagram extension we can include diagrams that are written in plain text. For example PlantUML or Ditaa diagrams. The extension offers a block processor where we include the diagram definitions in our Asciidoctor document. But there is also a block macro processor. With the block macro processor we can refer to an external file. The file is processed and the resulting image is in our output document.

Continue reading →

Awesome Asciidoctor: Use Only Block As List Item

Posted on by  
Hubert Klein Ikkink

When we define a list in Asciidoctor we usually have a list item that is a paragraph. But if we want to have a block as list item we need to add an extra element to make sure the block is parsed correctly as list item. Because a list item starts with a . or a * at the beginning of a line and a block also is defined on the beginning of the line, we must add the extra element. Together with the list item continuation (+) we can have a list with blocks.

Continue reading →

Awesome Asciidoctor: Grouping Floating Images

Posted on by  
Hubert Klein Ikkink

With Asciidoctor markup we can position images in our document. We can even float images, so text can next to an image, inside only below or about the image. We can also define multiple images to float, so the images are displayed on the same line next to each other. Any text that follows these images is also displayed next to the images. If we want only to have floating images, but the text starting under the images we can place the images inside an open block and assign the block the role float-group.

Continue reading →

Awesome Asciidoctor: Using Paragraphs in Lists With List Item Continuation

Posted on by  
Hubert Klein Ikkink

When we write a list in Asciidoctor we can simply create a list item by starting the line with a dot (.). To create a another list item we simply start a new line with a dot (.). But what if we want to add a list item with multiple paragraphs, or text and a source code block element. We can use the list item continuation (+) to indicate to Asciidoctor we want to keep these together for a single list item.

Continue reading →

Awesome Asciidoctor: Nested Tables

Posted on by  
Hubert Klein Ikkink

Defining tables in Asciidoctor is very easy. The start and end of the table are defined by |===. But if we want to add a new table to a table cell we cannot use the same syntax. To define a nested table we must replace the | separator with !. So instead of |=== to indicate the table boundaries we use !===. Also the cell separators are now ! instead of |. Finally we must make sure the table cell or column supports Asciidoc markup, so the table is properly created. We must configure the cell or column with a so the nested table is created.

Continue reading →

Awesome Asciidoctor: Using Filename Starting With Dot As Block Title

Posted on by  
Hubert Klein Ikkink

Adding a block title in Asciidoctor is easily done by adding a line at the top of the block that starts with a dot (.). The text following the dot is then used as the title of the block. But if the text of the title itself starts with a dot (.) Asciidoctor get’s confused. For example if we want to use a filename that starts with a dot (.filename) we must use different syntax to set the block title with the filename.

Continue reading →

shadow-left