== Values The value of a key may be one of the following types: * String - Font family name (e.g., Roboto) - Font style (normal, bold, italic, bold_italic) - Alignment (left, center, right, justify) - Color as hex string (e.g., #ffffff) - Image path - Enumerated type (where specified) - Text content (where specified) * Null (clears any previously assigned value) - _empty_ (i.e., no value specified) - null - ~ * Number (integer or float) with optional units (default unit is points) * Array - Color as RGB array (e.g., [51, 51, 51]) - Color CMYK array (e.g., [50, 100, 0, 0]) - Margin (e.g., [1in, 1in, 1in, 1in]) - Padding (e.g., [1in, 1in, 1in, 1in]) * Variable reference (e.g., $base_font_color) * Math expression Note that keys almost always require a value of a specific type, as documented in section *Keys*. === Inheritance Like CSS, inheritance is a principle feature in the *Asciidoctor PDF* theme language. For many of the properties, if a key is not specified, the key inherits the value applied to the parent content in the content hierarchy. This behavior saves you from having to specify properties unless you want to override the inherited value. The following keys are inherited: * font_family * font_color * font_size * font_style * text_transform * line_height (currently some exceptions) * margin_bottom (if not specified, defaults to $vertical_spacing) ==== Heading Inheritance Headings inherit starting from a specific heading level (e.g., `heading_h2_font_size`), then to the heading category (e.g., `heading_font_size`), then directly to the base value (e.g., `base_font_size`). Any setting from an enclosing context, such as a sidebar, is skipped. === Variables To save you from having to type the same value in your theme over and over, or to allow you to base one value on another, the theme language supports variables. Variables consist of the key name preceded by a dollar sign (`$`) (e.g., `$base_font_size`). Any qualified key that has already been defined can be referenced in the value of another key. (In order words, as soon as the key is assigned, it's available to be used as a variable). IMPORTANT: Variables are defined from top to bottom (i.e., in document order). Therefore, a variable must be defined before it is referenced. In other words, the path the variable refers to must be *above* the usage of that variable. For example, once the following line is processed, [source,yaml] ---- base: font_color: #333333 ---- the variable `$base_font_color` will be available for use in subsequent lines and will resolve to `#333333`. Let's say you want to make the font color of the sidebar title the same as the heading font color. Just assign the value `$heading_font_color` to the `$sidebar_title_font_color`. [source,yaml] ---- heading: font_color: #191919 sidebar: title: font_color: $heading_font_color ---- You can also use variables in math expressions to use one value to build another. This is commonly done to set font sizes proportionally.It also makes it easy to test different values very quickly. [source,yaml] ---- base: font_size: 12 font_size_large: $base_font_size * 1.25 font_size_small: $base_font_size * 0.85 ---- We'll cover more about math expressions later. ==== Custom Variables You can define arbitrary key names to make custom variables. This is one way to group reusable values at the top of your theme file. If you are going to do this, it's recommended that you organize the keys under a custom namespace, such as `brand`. For instance, here's how you can define your brand colors: [source,yaml,subs=attributes+] ---- brand: primary: #E0162B <1> secondary: '#FFFFFF' <2> alert: '0052A5' <3> ---- <1> To align with CSS, you may add a `+#+` in front of the hex color value. A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML. <2> You may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool. <3> The leading `+#+` on a hex value is entirely optional. However, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value. You can now use these custom variables later in the theme file: [source,yaml] ---- base: font_color: $brand_primary ---- === Math Expressions & Functions The theme language supports basic math operations to support calculated values. Like programming languages, multiple and divide take precedence over add and subtract. The following table lists the supported operations and the corresponding operator for each. [width="100%", cols="50%,50%", options="header", role="table-responsive mt-3"] |=== |Operation |Operator |multiply |* |divide |/ |add |+ |subtract |- |=== IMPORTANT: Operators must always be surrounded by a space on either side (e.g., 2 + 2, not 2+2). Here's an example of a math expression with fixed values. [source,yaml] ---- conum: line_height: 4 / 3 ---- Variables may be used in place of numbers anywhere in the expression: [source,yaml] ---- base: font_size: 12 font_size_large: $base_font_size * 1.25 ---- Values used in a math expression are automatically coerced to a float value before the operation. If the result of the expression is an integer, the value is coerced to an integer afterwards. IMPORTANT: Numeric values less than 1 must have a 0 before the decimal point (e.g., 0.85). The theme language also supports several functions for rounding the result of a math expression. The following functions may be used if they surround the whole value or expression for a key. round(...):: Rounds the number to the nearest half integer. floor(...):: Rounds the number up to the next integer. ceil(...):: Rounds the number down the previous integer. You might use these functions in font size calculations so that you get more exact values. [source,yaml] ---- base: font_size: 12.5 font_size_large: ceil($base_font_size * 1.25) ---- === Measurement Units Several of the keys require a value in points (pt), the unit of measure for the PDF canvas. A point is defined as 1/72 of an inch. If you specify a number without any units, the units defaults to pt. However, us humans like to think in real world units like inches (in), centimeters (cm), or millimeters (mm). You can let the theme do this conversion for you automatically by adding a unit notation next to any number. The following units are supported: [width="100%", cols="50%,50%", options="header", role="table-responsive mt-3"] |=== |Unit |Suffix |Centimeter |cm |Inches |in |Millimeter |mm |Percentage^[1]^ |%, vw, or vh |Points |pt (default) |=== A percentage with the % unit is calculated relative to the width or height of the content area. Viewport-relative percentages (vw or vh units) are calculated as a percentage of the page width or height, respectively. Currently, percentage units can only be used for placing elements on the title page or for setting the width of a block image. IMPORTANT: Numbers with more than two digits should be written as a float (e.g., 100.0), a math expression (e.g, 1 * 100), or with a unit (e.g., 100pt). Otherwise, the value may be misinterpreted as a hex color (e.g., '100') and could cause the converter to crash. Here's an example of how you can use inches to define the page margins: [source,yaml] ---- page: margin: [0.75in, 1in, 0.75in, 1in] ---- The order of elements in a measurement array is the same as it is in CSS: . top . right . bottom . left === Alignments The align subkey is used to align text and images within the parent container. ==== Text Alignments Text can be aligned as follows: * left * center * right * justify (stretched to each edge) ==== Image Alignments Images can be aligned as follows: * left * center * right === Font Styles In most cases, whereever you can specify a custom font family, you can also specify a font style. These two settings are combined to locate the font to # use. The following font styles are recognized: * normal (no style) * italic * bold * bold_italic === Text Transforms Many places where font properties can be specified, a case transformation can be applied to the text. The following transforms are recognized: * uppercase * lowercase * none (clears an inherited value) [CAUTION#transform-unicode-letters] ==== Since Ruby 2.4, Ruby has built-in support for transforming the case of any letter defined by Unicode. If you're using Ruby < 2.4, and the text you want to transform contains characters beyond the Basic Latin character set (e.g., an accented character), you must install either the `activesupport` or the `unicode` gem in order for those characters to be transformed. $ gem install activesupport or $ gem install unicode ==== // Additional transforms, such as capitalize, may be added in the future. === Colors The theme language supports color values in three formats: Hex:: A string of 3 or 6 characters with an optional leading `#`, optional surrounding quotes or both. RGB:: An array of numeric values ranging from 0 to 255. CMYK:: An array of numeric values ranging from 0 to 1 or from 0% to 100%. Transparent:: The special value `transparent` indicates that a color should not be used. ==== Hex The hex color value is likely most familiar to web developers. The value must be either 3 or 6 characters (case insensitive) with an optional leading hash (`#`), optional surrounding quotes or both. To align with CSS, you may add a `+#+` in front of the hex color value. A YAML preprocessor is used to ensure the value is not treated as a comment as it would normally be the case in YAML. You also may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool. In this case, the leading `+#+` on a hex value is entirely optional. Regardless, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value. The following are all equivalent values for the color red: [cols="8*m"] |=== |#ff0000 |#FF0000 |'ff0000' |'FF0000' |#f00 |#F00 |'f00' |'F00' |=== Here's how a hex color value appears in the theme file: [source,yaml] ---- base: font_color: #ff0000 ---- ==== RGB An RGB array value must be three numbers ranging from 0 to 255. The values must be separated by commas and be surrounded by square brackets. NOTE: An RGB array is automatically converted to a hex string internally, so there's no difference between ff0000 and [255, 0, 0]. Here's how to specify the color red in RGB: * [255, 0, 0] Here's how a RGB color value appears in the theme file: [source,yaml] ---- base: font_color: [255, 0, 0] ---- ==== CMYK A CMYK array value must be four numbers ranging from 0 and 1 or from 0% to 100%. The values must be separated by commas and be surrounded by square brackets. Unlike the RGB array, the CMYK array _is not_ converted to a hex string internally. PDF has native support for CMYK colors, so you can preserve the original color values in the final PDF. Here's how to specify the color red in CMYK: * [0, 0.99, 1, 0] * [0, 99%, 100%, 0] Here's how a CMYK color value appears in the theme file: [source,yaml] ---- base: font_color: [0, 0.99, 1, 0] ---- ==== Transparent It's possible to specify no color by assigning the special value `transparent`, as shown here: [source,yaml] ---- base: background_color: transparent ---- === Images An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax. Images are currently resolved relative to the value of the `pdf-stylesdir` attribute. The following image types (and corresponding file extensions) are supported: * PNG (.png) * JPEG (.jpg) * SVG (.svg) CAUTION: The GIF format (.gif) is not supported. Here's how an image is specified in the theme file as a bare image path: [source,yaml] ---- title_page: background_image: title-cover.png ---- Here's how the image is specified using the inline image macro: [source,yaml] ---- title_page: background_image: image:title-cover.png[] ---- Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment: [source,yaml] ---- title_page: logo_image: image:logo.png[width=250,align=center] ---- === Quoted String Some of the keys accept a quoted string as text content. The final segment of these keys is always named `content`. A content key accepts a string value. It's usually best to quote the string or use the {uri-symfony-yaml-format-strings}[YAML multi-line string syntax, {browser-window--new}]. Text content may be formatted using a subset of inline HTML. You can use the well-known elements such as ``, ``, ``, ``, ``, ``, ``, and ``. The `` element supports the `style` attribute, which you can use to specify the `color`, `font-weight`, and `font-style` CSS properties. You can also use the `rgb` attribute on the `` element to change the color or the `name` and `size` attributes on the `` element to change the font properties. If you need to add an underline or strikethrough decoration to the text, you can assign the `underline` or `line-through` to the `class` attribute on any aforementioned element. Here's an example of using formatting in the content of the menu caret: [source,yaml] ---- menu_caret_content: " \u203a " ---- NOTE: The string must be double quoted in order to use a Unicode escape code like `\u203a`. Additionally, normal substitutions are applied to the value of content keys for running content, so you can use most AsciiDoc inline formatting (e.g., `+*strong*+` or `+{attribute-name}+`) in the values of those keys.