Awesome Asciidoctor NotebookExperience Asciidoctor with code snippets

Hubert A. Klein Ikkink (mrhaki)

This book is for sale at http://leanpub.com/awesomeasciidoctornotebook

This version was published on 2016-11-11

This is a Leanpub book. Leanpub empowers authors and publishers with the LeanPublishing process. Lean Publishing is the act of publishing an in-progress ebook usinglightweight tools and many iterations to get reader feedback, pivot until you have theright book and build traction once you do.

© 2015 - 2016 Hubert A. Klein Ikkink (mrhaki)

Tweet This Book!Please help Hubert A. Klein Ikkink (mrhaki) by spreading the word about this book onTwitter!

The suggested tweet for this book is:

I just bought Awesome Asciidoctor Notebook with Asciidoctor blog posts bundled intoone book. #asciidoctor @mrhaki

The suggested hashtag for this book is #awesomeasciidoctornotebook.

Find out what other people are saying about the book by clicking on this link to searchfor this hashtag on Twitter:

https://twitter.com/search?q=#awesomeasciidoctornotebook

Also By Hubert A. Klein Ikkink (mrhaki)Groovy Goodness Notebook

Grails Goodness Notebook

Gradle Goodness Notebook

Spocklight Notebook

Ratpacked Notebook

This book is dedicated to my lovely family. I love you.

Contents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Changing Table and Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Table Column and Cell Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Changing the Grid and Frame of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . 5Span Cell over Rows and Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Repeating Cell Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Using Asciidoc in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Styling Columns and Cells in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Escaping Pipe Symbol in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16CSV and DSV Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Tables

Changing Table and ColumnWidth

When we define a table in Asciidoctor the columns all have the same width and the tablewill the whole width of the page. Of course we can change this when we define the table.We can change the table width with the width attribute. We specify the column width withthe cols attribute.

First we will change the width of the columns. We can specify proportional integer valuesor a percentage to specify the width of a column. In the following sample Asciidoctor filewe use proportional values in the first table. The first column has value 1 and the secondcolumn value 3. This means the second column should be 3 times as wide as the firstcolumn. In the second table the column width is defined with percentage values. The firstcolumn should occupy 60% of the table width and the last column the rest.

// Define table with proportional column width.

.Table with relative column widths (1,3)[cols="1,3"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

// Define table with column width as percentage values.

.Table with percentage column widths (60%,40%)[cols="60%,40%"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

When we transform the Asciidoctor source to HTML we get the following result:

Tables 2

We see in the examples that the width of the table is the same as the width of the page. Tomake a smaller table we set the width attribute for a table. The value must be a percentage.Let’s create a sample Asciidoctor file and define a table with a width of 50%:

// Define table with default width for comparison.

.Table full width (default)|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

// Define new table and set width to 50%.

.Table half width (50%)[width="50%"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

And if we look at the generated HTML for example we can see the second table is half thewidth of the first:

Tables 3

Written with Asciidoctor 1.5.1.

Original blog post written on November 07, 2014.

Table Column and Cell Alignment

Creating a table with Asciidoctor is a breeze. The syntax is very clear and the HTML outputshows a very nice looking table. But there is also a lot of configuration we can do when wedefine a table. For example by default all columns are left aligned, but we can change thisto have values centered or right aligned in columns.We can even set the vertical alignmentfor columns. And if this is not enough we can change the horizontal and vertical alignmentper cell.

Let’s start with a simple table with three columns.Wewant the first column to be centered,themiddle column to be left aligned and the last column should be right aligned. To achievethis we must configure the cols attribute for our table definition. We use the followingsymbols to define the alignment:

• <: left align values (default)• >: right align values• ˆ: center values

We create a new Asciidoctor file with the following contents:

// File: table.adoc

// We define a table with 3-columns.// First column is centered,// second column is left aligned and// third column is right aligned.

[cols="^,<,>", options="header"]|===

| Name| Description| Version

Tables 4

| Asciidoctor| Awesome way to write documentation| 1.5.0|===

When we create HTML output from this source we get the following output:

We have now defined the horizontal alignment. To include vertical alignment we mustadd dot (.) to the horizontal alignment value and then the vertical alignment value. Thefollowing vertical alignment values can be used:

• <: top align values (default)• >: bottom align values• ˆ: center values

In the following sample Asciidoctor file we add vertical alignment configuration to ourprevious table:

// File: table.adoc

// We define a table with 3-columns.// First column is centered and bottom aligned,// second column is left and top aligned and// third column is right aligned and centered vertically.

[cols="^.>,<.<,>.^", options="header"]|===

| Name| Description| Version

| Asciidoctor| Awesome way to write documentation| 1.5.0|===

We get the following HTML table when we process that source file:

Tables 5

Finally we can alter the horizontal and vertical alignment per cell. We use the alignmentconfiguration symbols before the pipe symbol (|) of a cell definition. This overrules anyalignment configuration set in the cols definition. In the next Asciidoctor file we combineall these settings for a table:

// File: table.adoc

// We define a table with 3-columns.// The row header has all cell values// centered.// The first table row cell is right aligned.// The last table row cell is horizontal// and vertical centered.

[cols="3*", options="header"]|===

^| Name^| Description^| Version

>| Asciidoctor| Awesome way to write documentation^.^| 1.5.0|===

And when we look at the output we see all alignment configuration applied to our table:

Written with Asciidoctor 1.5.0.

Original blog post written on November 06, 2014.

Changing the Grid and Frame of Tables

We can change the frames and grid of tables we define in Asciidoctor. We use the framesattribute to change the outside frame of a table. We can choose between topbot for topand bottom, sides for only a frame at the sides of the table, none if we don’t want a frame.The default value all create a frame around our table with top, sides and bottom.

Tables 6

To change the inner grid of a table we use the grids table attribute. The default value alldisplays a grid for columns and rows inside the table. The value cols only displays a gridbetween columns, value rows display a grid between rows and with value none there willbe no grid inside our table.

The following Asciidoc sample shows the definition of four tables with different values forthe cols table attribute:

.Table with top and bottom frame (topbot)[frame="topbot"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with no frame (none)[frame="none"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with only sides frame (sides)[frame="sides"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with default frame (all)[frame="all"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

When we generate output using the HTML backend we get the following result:

Tables 7

In the next sample we have four tables with different values for the cols attribute:

.Table with no grid (none)[grid="none", frame="none"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with only columns grid (cols)[grid="cols", frame="none"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with only rows grid (rows)[grid="rows", frame="none"]|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

.Table with default rows and columns grid (all)[grid="all", frame="none"]

Tables 8

|===| Name | Description

| Asciidoctor| Awesome way to write documentation

|===

And we get the following output when we transform this source to HTML:

Written with Asciidoctor 1.5.1.

Original blog post written on November 20, 2014.

Span Cell over Rows and Columns

When we define a table in Asciidoctor we might want to span a cell over multiple columnsor rows, instead of just a single column or row.We can do this using a cell specifier with thefollowing format: column-span.row-span+. The values for column-span and row-span definethe number of columns and rows the cell must span. We put the cell specifier before thepipe symbol (|) in our table definition.

In the following example Asciidoctor markup we have three tables. In the first table wespan a cell over 2 columns, the second table spans a cell over 2 rows and in the final tablewe span a cell over both 2 columns and rows.

Tables 9

== Table cell span

.Cell spans columns|===| Name | Description

| Asciidoctor| Awesome way to write documentation

// This cell spans 2 columns, indicated// by the number before the + sign.// The + sign// tells Asciidoctor to span this// cell over multiple columns.2+| The statements above say it all

|===

.Cell spans rows|===| Name | Description

// This cell spans 2 rows,// because the number after// the dot (.) specifies the number// of rows to span. The + sign// tells Asciidoctor to span this// cell over multiple rows..2+| Asciidoctor| Awesome way to write documentation

| Works on the JVM

|===

.Cell spans both rows and columns|===| Col1 | Col2 | Col 3

// We can combine the numbers for// row and column span within one// cell specifier.// The number before the dot (.)// is the number of columns to span,// the number after the dot (.)// is the number of rows to span.2.2+| Cell spans 2 cols, 2 rows| Row 1, Col 3

| Row 2, Col 3

|===

Tables 10

If we transform our source to HTML we get the following tables:

Written with Asciidoctor 1.5.1.

Original blog post written on December 04, 2014.

Repeating Cell Contents

With Asciidoctor we can repeat cell contents if we prefix the cell separator pipe symbol (|)with the number of times we want to repeat the cell followed by an asterisk (*).

In the following example Asciidoctor source file we define two tables and add 2* to cellsthat we want to repeat two times:

// 3-column table, where the first column// cell value is not repeated, and the// cell value for columns 2 and 3 is// repeated.|===| Column | Value | Value

| Name2*| Asciidoctor

| Description2*| Awesome way to write documentation

Tables 11

|===

// One column table. So the repeated// cells are each on their own row.|===| Column

2*| Asciidoctor

2*| Awesome way to write documentation

|===

When we generate a HTML document from this source we see the following result:

Written with Asciidoctor 1.5.1.

Original blog post written on December 02, 2014.

Using Asciidoc in Tables

When we define a table in Asciidoctor and want to use Asciidoc in a table cell it is notinterpreted as Asciidoc by default. The text is literally shown and this might not be whatwe expect. But we can force Asciidoctor to interpret the cell contents as Asciidoctor.

Let’s start with a very simple table. The last cell of the first row contains some Asciidocmarkup:

Tables 12

:icons: font

// Simple table where we apply some// Asciidoc markup in the cell contents.

|===| Name | Description

| Asciidoctor| NOTE: *Awesome* way to write documentation

|===

When we transform this Asciidoctor source to HTML we see the following output:

Notice that we don’t get a nice image for our NOTE is not shown as image when it used in atable cell.

To change this behavior we can configure the table. We can configure a column to haveAsciidoc content that needs to be interpreted or we can configure at cell level we want thecontents to be interpreted as Asciidoc. We use the character a in the cols attribute whenwe define the table. Or we use the character a before the table cell separator (|). In thenext sample Asciidoctor file we use both ways to make sure the cell contents is Asciidocmarkup that needs to be transformed as well:

:icons: font

// We use the cols attribute for our table// and specify that the contents of the second// column is Asciidoc markup.

[cols=",a"]|===| Name | Description

| Asciidoctor| NOTE: *Awesome* way to write documentation

|===

// Or we configure per cell the contents// is Asciidoc markup.

|===| Name | Description

| Asciidoctor

Tables 13

// We specify for this specific cell the// contents is Asciidoc that needs to// be processed.a| NOTE: *Awesome* way to write documentation

|===

Once we have defined the table we get the following generated HTML:

And this time the cell contents is transformed as well.

Written with Asciidoctor 1.5.1.

Original blog post written on November 10, 2014.

Styling Columns and Cells in Tables

In a previous post we learned how to use Asciidoc markup in a table. The a character isjust one of many styles we can define in our table. In this blog post we see which styleoptions we have. We can either use the cols attribute to define a style for a whole columnor specify per cell the style.

We can use the following styles:

• e: emphasized• a: Asciidoc markup• m: monospace• h: header style, all column values are styled as header• s: strong• l: literal, text is shown in monospace font and line breaks are kept• d: default• v: verse, keeps line breaks

The following Asciidoctor source uses the different styles as cols attribute values:

Tables 14

.Table with column style e,a,m[cols="e,a,m"]|===| Emphasized (e) | Asciidoc (a) | Monospaced (m)

| Asciidoctor| NOTE: *Awesome* way to write documentation| It is just code

|===

.Table with column style h,s,l[cols="h,s,l"]|===| Header (h) | Strong (s) | Literal (l)

| Asciidoctor| Awesome way to write documentation| It isjust code

|===

.Table with column style d,v[cols="d,v"]|===| Default (d) | Verse (v)

| Asciidoctor| Awesome wayto writedocumentation

|===

When we transform this into HTML using the Asciidoctor HTML backend we get thefollowing result:

Tables 15

We can also override a column styling per cell. We must put the correct styling characterbefore the pipe symbol (|), so the contents of the cell is styled differently:

Table with row style e,a,m in second row|===| Emphasized | Asciidoc | Monospaced

| Asciidoctor| NOTE: *Awesome* way to write documentation| It is just code

e| Asciidoctora| NOTE: *Awesome* way to write documentationm| It is just code

|===

And the following HTML is generated when we process this Asciidoctor source:

Tables 16

Written with Asciidoctor 1.5.1.

Original blog post written on November 10, 2014.

Escaping Pipe Symbol in Tables

To define a table in Asciidoc is easy. Table cells are separated basically by pipe symbols (|).But if we want to use a pipe-symbol as cell content we need to escape the pipe-symbolwith a backslash (\)

The following Asciidoc code is transformed to a correct HTML table output:

.Sample table with pipe-symbol in cell content|===| Operator | Method

| a + b| a.plus(b)

| a - b| a.minus(b)

| a \| b| a.or(b)

|===

The generated HTML table looks like this for example:

Tables 17

Generated with Asciidoctor 0.1.4.

Original blog post written on June 04, 2014.

CSV and DSV Tables

With Asciidoctor we can create tables where the header and rows are in CSV (CommaSeparated Values) and DSV (Delimiter Separated Values) format. Normally we use a pipe-symbol (|) to separate cell values. This is actually PSV (Prefix Separated Values) :-).

In the following Asciidoctor markup we create a very simple table with a header and tworows using CSV:

= Tables

== CSV table

[format="csv", options="header"]|===Writing tools, AwesomenessAsciidoctor, Oh yeah!MS Word, No!|===

We generate this into HTML and we get the following result:

Asciidoctor provides also another way to define the above table:

Tables 18

= Tables

== CSV table

// Define table using CSV syntax.// The start and end of the table is defined// as ,=== instead of |===.// Also the header row is followed by new line,// to indicate it is the header row.

,===Writing tools, Awesomeness

Asciidoctor, Oh yeah!MS Word, No!,===

// We can also specify a separator.

[format="csv", separator=";", options="header"]|===Name;DescriptionAsciidoctor;Awesome way to write documentation|===

The previous samples used a comma to separate values, but we can also use colon (:). Thenext sample contains tables defined with DSV:

== DSV table

[format="dsv", options="header"]|===Writing tools:AwesomenessAsciidoctor:Oh yeah!MS Word:No!|===

// Alternative syntax:

:===Writing tools: Awesomeness

Asciidoctor: Oh yeah!MS Word: No!:===

With the include directive we can also include data from an external CSV of DSV file tocreate a table (of course also the traditional pipe-symbol separated format can be in anexternal file):

Tables 19

= Table with external data

[format="csv", options="header"]|===include::tools.csv[]|===

The file tools.cv has the following contents:

Writing tools, AwesomenessAsciidoctor, Oh yeah!MS Word, No!

Code written with Asciidoctor 1.5.0.

Original blog post written on November 05, 2014.