Coding

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

Awesome Asciidoctor: Trick To Use Caption Labels And Numbers In References

Posted on by  
Hubert Klein Ikkink

In Asciidoctor we can add an anchor with an ID to a section or title and then reference it in a link. The title of the section is used as link text. We can alter that when we define the link, but if we rely on the default behaviour we create a title for our section including the caption label and number. This way the created link points to the correct section and the text contains the caption text and number for that section.

Continue reading →

shadow-left