ifeval Directive

Content between ifeval and endif gets included if the expression inside the square brackets evaluates to true.

Example 1. ifeval example
ifeval::[{sectnumlevels} == 3]
If the `sectnumlevels` attribute has the value 3, this sentence is included.
endif::[]

The ifeval directive does not have a single-line or long-form variant like ifdef and ifndef.

Unlike ifdef and ifndef, you cannot terminate a specific ifeval directive using its complement. For example, the following ifeval block is not valid:

Example 2. Invalid ifeval terminator
ifeval::[<condition>]
conditional content
endif::[<condition>]

You can only terminate the previous ifeval directive using an anonymous endif::[] directive, as shown here:

Example 3. Valid ineval terminator
ifeval::[<condition>]
conditional content
endif::[]

If you’re mixing ifeval directives with ifdef or ifndef directives, you should always terminate the ifdef and ifndef directives by name (endif::attribute-name[]) so the ifeval directive does not get terminated prematurely.

Anatomy

The expression consists of a left-hand value and a right-hand value with an operator in between.

Example 4. ifeval expression examples
ifeval::[2 > 1]
...
endif::[]

ifeval::["{backend}" == "html5"]
...
endif::[]

ifeval::[{sectnumlevels} == 3]
...
endif::[]

// the value of outfilesuffix includes a leading period (e.g., .html)
ifeval::["{docname}{outfilesuffix}" == "main.html"]
...
endif::[]

Values

Each expression value can reference the name of zero or more AsciiDoc attribute using the attribute reference syntax (for example, {backend}).

Attribute references are resolved (substituted) first. Once attributes references have been resolved, each value is coerced to a recognized type.

When you expect the attribute reference to resolve to a string, that is, a sequence of characters, enclose that side of the expression in quotes. For example:

Example 5. ifeval that compares two string expressions
ifeval::["{backend}" == "html5"]

Whereas if you expect the attribute to resolve to a number, you do not need to enclose the expression in quotes. In this case, the values will be compared as numbers. The same rule applies to boolean values.

The following values types are recognized:

number

Either an integer or floating-point value.

quoted string

Enclosed in either single (') or double (") quotes.

boolean

Literal value of true or false.

How value type coercion works

If a value is enclosed in quotes, the characters between the quotes are preserved and coerced to a string.

If a value is not enclosed in quotes, it is subject to the following type coercion rules:

  • an empty value becomes nil (aka null).

  • a value of true or false becomes a boolean value.

  • a value of only repeating whitespace becomes a single whitespace string.

  • a value containing a period becomes a floating-point number.

  • any other value is coerced to an integer value.

Operators

The value on each side is compared using the operator to derive an outcome.

==

Checks if the two values are equal.

!=

Checks if the two values are not equal.

<

Checks whether the left-hand side is less than the right-hand side.

<=

Checks whether the left-hand side is less than or equal to the right-hand side.

>

Checks whether the left-hand side is greater than the right-hand side.

>=

Checks whether the left-hand side is greater than or equal to the right-hand side.

The operators follow the same rules as operators in Ruby.