Caution
This is an advanced topic. If you are new to AsciiDoc you should skip this chapter until you have practiced and gotten better at AsciiDoc. I don’t recommend this to new people.

When you use AsciiDoctor as the rendering app for AsciiDoc content you can render the content in a conditional way.

Why would you want to publish based on a condition, you might ask. As an example, I wrote a genealogy book that had details I wanted to share with family, but not with the general public. So I made one condition "public" which only showed information about people who have already died. The other condition was "living" which surrounded personal information like date of birth, and other details we don’t want floating around in public.

AsciiDoctor has a way to facilitate conditional publishing, or as Dan Allen calls it, conditional pre-processing.

To use conditional publishing we first set a flag of sorts in the book attributes by inventing our own special conditional code. For example in my genealogy book, the flags or attributes were "living" and "public". In another book, I might want to use "eBook" and "printPDF" to identify sections of content. You may makeup whatever codes you like to flag AsciiDoctor. The key thing is to add your flag as an attribute in the front of your book.

Warning
Do not add a blank line between your conditional attribute and the other book attributes or it may not work.

Next we surround the content we want conditional with a small set of codes that tell AsciiDoctor to check the attribute before rendering this part.

For example, a paragraph in a chapter or section might have a table which only works well in PDF, not eBooks. So I would add the conditional codes around the table for "printPDF" and have a bulleted form of the content wrapped with "eBook" conditional flag. The only one to show up would be the one with the attribute set at the front of the book.

= Example Conditional Publishing Book
:author: Kevin Lanham
:printPDF: (1)

This paragraph shows up in all conditions. (2)

ifdef::printPDF[] (3)
This portion was made for PDF to facilitate printing.
Perhaps this section has a table that only renders well in PDF format. (4)
endif::[] (5)

ifdef::eBook[] (6)
This portion was made for eBooks. (7)
A bulleted list might replace the table in this section.
endif::[] (8)
  1. The printPDF is the attribute that flags AsciiDoctor to render all the common content and the content marked by this attribute.

  2. This paragraph is an example of common content which will render for all conditions.

  3. This is the beginning code for the condition "printPDF".

  4. This is the "printPDF" conditional content.

  5. This is the ending code for the conditional "printPDF".

  6. This is the beginning code for the condition "eBook".

  7. This is the "eBook" conditional content.

  8. This is the ending code for the conditional "eBook".

Image

Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview