asciidoctor-pdf 1.5.0.alpha.17 → 1.5.0.beta.1

data/docs/theming-guide.adoc

@@ -44,26 +44,28 @@ toc::[]
 
 == Language Overview
 
-The theme language in Asciidoctor PDF is based on the http://en.wikipedia.org/wiki/YAML[YAML] data format and incorporates many concepts from CSS and SASS.
-Therefore, if you have a background in web design, the theme language should be immediately familiar to you.
+The Asciidoctor PDF theme language is described using the http://en.wikipedia.org/wiki/YAML[YAML] data format and incorporates many _concepts_ from CSS and SASS.
+Therefore, if you have a background in web design, the terminology should be immediately familiar to you.
+*Note, however, that the theming system isn't actually CSS.*
 
 Like CSS, themes have both selectors and properties.
 Selectors are the component you want to style.
 The properties are the style elements of that component that can be styled.
-All selector names are implicit (e.g., `heading`), so you customize the theme primarily by manipulating pre-defined property values (e.g., `font_size`).
+All selector names are implicit (e.g., `heading`), so you customize the theme primarily by manipulating pre-defined property values (e.g., `font-size`).
 
 [NOTE]
 ====
 The theme language in Asciidoctor PDF supports a limited subset of the properties from CSS.
 Some of these properties have different names from those found in CSS.
 
-* Underscores (`_`) can be used in place of hyphens (`-`) for all property names in the theme language.
-* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font_style` property (allowed values: `normal`, `bold`, `italic` and `bold_italic`).
-* The `text_align` property from CSS is the `align` property in the theme language.
-* The `color` property from CSS is the `font_color` property in the theme language.
+* An underscore (`_`) may be used in place of a hyphen (`-`) in all property names (so you may use `font_family` or `font-family`).
+* An underscore (`_`) may be used in place of a hyphen (`-`) in all variable names (so you may use `$base_font_family` or `$base-font-family`).
+* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` property (allowed values: `normal`, `bold`, `italic` and `bold_italic`).
+* The `align` property in the theme language is roughly equivalent to the `text-align` property in CSS.
+* The `font-color` property in the theme language is equivalent to the `color` property in CSS.
 ====
 
-A theme (or style) is described in a YAML-based data format and stored in a dedicated theme file.
+A theme is described in a YAML-based data format and stored in a dedicated theme file.
 YAML is a human-friendly data format that resembles CSS and helps to describe the theme.
 The theme language adds some extra features to YAML, such as variables, basic math, measurements and color values.
 These enhancements will be explained in detail in later sections.
@@ -80,28 +82,49 @@ page:
   margin: [0.75in, 1in, 0.75in, 1in]
   size: Letter
 base:
-  font_color: #333333
-  font_family: Times-Roman
-  font_size: 12
-  line_height_length: 17
-  line_height: $base_line_height_length / $base_font_size
-vertical_spacing: $base_line_height_length
+  font-color: #333333
+  font-family: Times-Roman
+  font-size: 12
+  line-height-length: 17
+  line-height: $base-line-height-length / $base-font-size
+vertical-spacing: $base-line-height-length
 heading:
-  font_color: #262626
-  font_size: 17
-  font_style: bold
-  line_height: 1.2
-  margin_bottom: $vertical_spacing
+  font-color: #262626
+  font-size: 17
+  font-style: bold
+  line-height: 1.2
+  margin-bottom: $vertical-spacing
 link:
-  font_color: #002FA7
-outline_list:
-  indent: $base_font_size * 1.5
+  font-color: #002FA7
+outline-list:
+  indent: $base-font-size * 1.5
+footer:
+  height: $base-line-height-length * 2.5
+  line-height: 1
+  recto:
+    right:
+      content: '{page-number}'
+  verso:
+    left:
+      content: $footer-recto-right-content
 ----
 
 When creating a new theme, you only have to define the keys you want to override from the base theme, which is loaded prior to loading your custom theme.
 All the available keys are documented in <<Keys>>.
 The converter uses the information from the theme map to help construct the PDF.
 
+Instead of writing a theme from scratch, you can extend the default theme using the `extends` key as follows:
+
+[source,yaml]
+----
+extends: default
+base:
+  font-color: #ff0000
+----
+
+You can also point the extends key at another custom theme to extend from it.
+Currently, the base theme is always loaded first.
+
 WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `literal` categories.
 Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.
 
@@ -121,27 +144,27 @@ Once the theme is loaded, all keys are flattened into a single map of qualified
 Nesting is simply a shorthand way of organizing the keys.
 In the end, a theme is just a map of key/value pairs.
 
-Nested keys are adjoined to their parent key with an underscore (`_`).
-This means the selector part (e.g., `link`) is combined with the property name (e.g., `font_color`) into a single, qualified key (e.g., `link_font_color`).
+Nested keys are adjoined to their parent key with an underscore (`_`) or hyphen (`-`).
+This means the selector part (e.g., `link`) is combined with the property name (e.g., `font-color`) into a single, qualified key (e.g., `link_font_color` or `link-font-color`).
 
 For example, let's assume we want to set the base (i.e., global) font size and color.
 These keys may be written longhand:
 
 [source,yaml]
 ----
-base_font_color: #333333
-base_font_family: Times-Roman
-base_font_size: 12
+base-font-color: #333333
+base-font-family: Times-Roman
+base-font-size: 12
 ----
 
-Or, to avoid having to type the prefix `base_` multiple times, the keys may be written hierarchically:
+Or, to avoid having to type the prefix `base-` multiple times, the keys may be written as a hierarchy:
 
 [source,yaml]
 ----
 base:
-  font_color: #333333
-  font_family: Times-Roman
-  font_size: 12
+  font-color: #333333
+  font-family: Times-Roman
+  font-size: 12
 ----
 
 Or even:
@@ -155,8 +178,8 @@ base:
     size: 12
 ----
 
-Each level of nesting must be indented by two more spaces of indentation than the parent level.
-Also note the presence of the colon after each key name.
+Each level of nesting must be indented by two spaces from the indentation of the parent level.
+Also note the presence of the colon (`:`) after each key name.
 
 == Values
 
@@ -166,7 +189,7 @@ The value of a key may be one of the following types:
   - 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)
+  - Color as hex string (e.g., 'ff0000', #ff0000, or '#ff0000')
   - Image path
   - Enumerated type (where specified)
   - Text content (where specified)
@@ -180,7 +203,7 @@ The value of a key may be one of the following types:
   - 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)
+* Variable reference (e.g., $base_font_color or $base-font-color)
 * Math expression
 
 Note that keys almost always require a value of a specific type, as documented in <<Keys>>.
@@ -193,24 +216,24 @@ This behavior saves you from having to specify properties unless you want to ove
 
 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)
+* 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`).
+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`).
+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).
 
@@ -223,21 +246,21 @@ For example, once the following line is processed,
 [source,yaml]
 ----
 base:
-  font_color: #333333
+  font-color: #333333
 ----
 
-the variable `$base_font_color` will be available for use in subsequent lines and will resolve to `#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`.
+Just assign the value `$heading-font-color` to the `$sidebar-title-font-color`.
 
 [source,yaml]
 ----
 heading:
-  font_color: #191919
+  font-color: #191919
 sidebar:
   title:
-    font_color: $heading_font_color
+    font-color: $heading-font-color
 ----
 
 You can also use variables in math expressions to use one value to build another.
@@ -247,9 +270,9 @@ 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
+  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.
@@ -265,22 +288,22 @@ For instance, here's how you can define your brand colors:
 [source,yaml,subs=attributes+]
 ----
 brand:
-  primary: #E0162B {conum-guard-yaml} <1>
-  secondary: '#FFFFFF' {conum-guard-yaml} <2>
-  alert: '0052A5' {conum-guard-yaml} <3>
+  primary-color: #E0162B {conum-guard-yaml} <1>
+  secondary-color: '#FFFFFF' {conum-guard-yaml} <2>
+  alert-color: '0052A5' {conum-guard-yaml} <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.
+<1> To align with CSS, you may add `+#+` in front of the hex color value to coerce it to a string.
+A YAML preprocessor is used to ensure the value is not treated as a comment as 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.
+However, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value (for example, 000000 would become 0, so use '000000' or #000000 instead).
 
 You can now use these custom variables later in the theme file:
 
 [source,yaml]
 ----
 base:
-  font_color: $brand_primary
+  font-color: $brand-primary-color
 ----
 
 === Math Expressions & Functions
@@ -314,7 +337,7 @@ Here's an example of a math expression with fixed values.
 [source,yaml]
 ----
 conum:
-  line_height: 4 / 3
+  line-height: 4 / 3
 ----
 
 Variables may be used in place of numbers anywhere in the expression:
@@ -322,8 +345,8 @@ 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
+  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.
@@ -343,8 +366,8 @@ You might use these functions in font size calculations so that you get more exa
 [source,yaml]
 ----
 base:
-  font_size: 12.5
-  font_size_large: ceil($base_font_size * 1.25)
+  font-size: 12.5
+  font-size-large: ceil($base-font-size * 1.25)
 ----
 
 === Measurement Units
@@ -382,9 +405,6 @@ The following units are supported:
 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]
@@ -461,7 +481,7 @@ or
 
 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.
+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.
@@ -469,10 +489,12 @@ Transparent:: The special value `transparent` indicates that a color should not
 ==== 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.
+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.
+A YAML preprocessor is used to ensure the value is not treated as a comment as would normally be the case in YAML.
+That same preprocessor will also coerce a primitive value to a string if `color` is the name of the last segment in the key (e.g., `font-color`).
+This avoids the problem of 000 becoming 0 (and similar implicit conversions) when the theme file is parsed.
 
 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.
@@ -498,7 +520,7 @@ Here's how a hex color value appears in the theme file:
 [source,yaml]
 ----
 base:
-  font_color: #ff0000
+  font-color: #ff0000
 ----
 
 ==== RGB
@@ -517,7 +539,7 @@ Here's how a RGB color value appears in the theme file:
 [source,yaml]
 ----
 base:
-  font_color: [255, 0, 0]
+  font-color: [255, 0, 0]
 ----
 
 ==== CMYK
@@ -538,7 +560,7 @@ Here's how a CMYK color value appears in the theme file:
 [source,yaml]
 ----
 base:
-  font_color: [0, 0.99, 1, 0]
+  font-color: [0, 0.99, 1, 0]
 ----
 
 ==== Transparent
@@ -548,13 +570,14 @@ It's possible to specify no color by assigning the special value `transparent`,
 [source,yaml]
 ----
 base:
-  background_color: transparent
+  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.
+Images in the theme file are currently resolved relative to the value of the `pdf-themesdir` attribute.
+(If `pdf-theme` is a path that ends in `.yml`, and `pdf-themesdir` is not set, then the images are resolved relative to the directory of the path specified by `pdf-theme`).
 
 The following image types (and corresponding file extensions) are supported:
 
@@ -562,35 +585,34 @@ The following image types (and corresponding file extensions) are supported:
 * JPEG (.jpg)
 * SVG (.svg)
 
-CAUTION: The GIF format (.gif) is not supported.
+CAUTION: The GIF format (.gif) and BMP format (.bmp) are not supported unless you're using prawn-gmagick.
+See https://github.com/asciidoctor/asciidoctor-pdf#supporting-additional-image-file-formats[support for additional image file formats] for details.
 
 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
+title-page:
+  background-image: title-cover.png
 ----
 
-In this case, the image is resolved relative to theme directory.
-
 Here's how the image is specified using the inline image macro:
 
 [source,yaml]
 ----
-title_page:
-  background_image: image:title-cover.png[]
+title-page:
+  background-image: image:title-cover.png[]
 ----
 
-In this case, the image is resolved relative to the value of the `imagesdir` attribute.
-Wrapping the value in the image macro sends a hint to the converter to resolve it just like other images.
+In either case, the image is resolved relative to the value of the `pdf-themesdir` attribute, as previously described.
 
-Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment:
+Like in the AsciiDoc syntax, wrapping the value in the image macro allows you to specify other settings, such as `pdfwidth`, `fit`, and/or `align`.
+For example:
 
 [source,yaml]
 ----
-title_page:
-  logo_image: image:logo.png[width=250,align=center]
+title-page:
+  logo-image: image:logo.png[width=250,align=center]
 ----
 
 === Quoted String
@@ -611,7 +633,7 @@ Here's an example of using formatting in the content of the menu caret:
 
 [source,yaml]
 ----
-menu_caret_content: " <font size=\"1.15em\"><color rgb=\"#b12146\">\u203a</color></font> "
+menu-caret-content: " <font size=\"1.15em\"><color rgb=\"#b12146\">\u203a</color></font> "
 ----
 
 NOTE: The string must be double quoted in order to use a Unicode escape code like `\u203a`.
@@ -626,6 +648,8 @@ If you want to use custom fonts, you must first declare them in your theme file.
 IMPORTANT: Asciidoctor has no challenge working with Unicode.
 In fact, it prefers Unicode and considers the entire range.
 However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters.
+That means you need to provide a font (at least a fallback font) that contains glyphs for all the characters you want to use.
+If you don't, you may notice that characters are missing.
 There's nothing Asciidoctor can do to convince PDF to work with extended characters without the right fonts in play.
 
 === Built-In (AFM) Fonts
@@ -647,13 +671,13 @@ The names of the built-in fonts (for general-purpose text) are as follows:
 |===
 
 Using a built-in font requires no additional files.
-You can use the key anywhere a `font_family` property is accepted in the theme file.
+You can use the key anywhere a `font-family` property is accepted in the theme file.
 For example:
 
 [source,yaml]
 ----
 base:
-  font_family: Times-Roman
+  font-family: Times-Roman
 ----
 
 However, when you use a built-in font, the characters you can use in your document are limited to the characters in the WINANSI (http://en.wikipedia.org/wiki/Windows-1252[Windows-1252]) code set.
@@ -673,11 +697,14 @@ When using the built-in PDF (AFM) fonts on a block of content in your AsciiDoc d
  The following text could not be fully converted to the Windows-1252 character set:
  | <string with unknown glyph>
 
-This behavior differs from the default behavior in Prawn, which simply crashes.
+This behavior differs from the default behavior in Prawn, which is to simply crash.
 
 You'll often see this warning if you're using callouts in your document and you haven't specified a TrueType font in your theme.
 To prevent this warning, you need to specify a TrueType font.
 
+When using a TrueType font, you will get no warning for a missing glyph.
+That's a consequence of how Prawn works and is outside of Asciidoctor PDF's control.
+
 For more information about how Prawn handles character encodings for built-in fonts, see https://github.com/prawnpdf/prawn/blob/master/CHANGELOG.md#vastly-improved-handling-of-encodings-for-pdf-built-in-afm-fonts[this note in the Prawn CHANGELOG].
 ****
 
@@ -731,7 +758,7 @@ Name the files as follows:
 * roboto-bold.ttf (_originally Roboto-Bold.ttf_)
 * roboto-bold_italic.ttf (_originally Roboto-BoldItalic.ttf_)
 
-Next, declare the font under the `font_catalog` key at the top of your theme file, giving it a unique key (e.g., `Roboto`).
+Next, declare the font under the `font-catalog` key at the top of your theme file, giving it a unique key (e.g., `Roboto`).
 
 [source,yaml]
 ----
@@ -744,18 +771,18 @@ font:
       bold_italic: roboto-bold_italic.ttf
 ----
 
-You can use the key that you assign to the font in the font catalog anywhere the `font_family` property is accepted in the theme file.
+You can use the key that you assign to the font in the font catalog anywhere the `font-family` property is accepted in the theme file.
 For instance, to use the Roboto font for all headings, you'd use:
 
 [source,yaml]
 ----
 heading:
-  font_family: Roboto
+  font-family: Roboto
 ----
 
 When you execute Asciidoctor PDF, you need to specify the directory where the fonts reside using the `pdf-fontsdir` attribute:
 
- $ asciidoctor-pdf -a pdf-style=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
+ $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
 
 WARNING: Currently, all fonts referenced by the theme need to be present in the directory specified by the `pdf-fontsdir` attribute.
 
@@ -820,7 +847,7 @@ font:
       bold_italic: droid-sans-fallback.ttf
 ----
 
-Next, add the key name to the `fallbacks` key under the `font_catalog` key.
+Next, add the key name to the `fallbacks` key under the `font-catalog` key.
 The `fallbacks` key accepts an array of values, meaning you can specify more than one fallback font.
 However, we recommend using a single fallback font, if possible, as shown here:
 
@@ -849,7 +876,7 @@ Of course, make sure you've configured your theme to use your custom font:
 [source,yaml]
 ----
 base:
-  font_family: Roboto
+  font-family: Roboto
 ----
 
 That's it!
@@ -863,9 +890,9 @@ This section lists all the keys that are available when creating a custom theme.
 The keys are organized by category.
 Each category represents a common prefix under which the keys are typically nested.
 
-TIP: Keys can be nested wherever an underscore (`_`) appears in the name.
+TIP: Keys can be nested wherever an underscore (`_`) or hyphen (`-`) appears in the name.
 This nested structure is for organizational purposes only.
-All keys are flatted when the theme is loaded (e.g., `align` nested under `base` becomes `base_align`).
+All keys are flatted when the theme is loaded (e.g., `align` nested under `base` becomes `base-align`).
 
 The converter uses the values of these keys to control how most elements are arranged and styled in the PDF.
 The default values listed in this section get inherited from the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/base-theme.yml[base theme].
@@ -876,6 +903,34 @@ When creating a theme, all keys are optional.
 Required keys are provided by the base theme.
 Therefore, you only have to declare keys that you want to override.
 
+[#keys-extends]
+=== Extends
+
+A theme can extend another theme using the `extends` key.
+The extends key accepts either a single value or an array of values.
+Each value is interpreted as a filename.
+If the filename equals `default`, it resolves to the location of the default (built-in) theme.
+If the filename is absolute, it's used as is.
+If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
+Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).
+
+Currently, the base theme is always loaded first.
+Then, the files referenced by the extends key are loaded in order.
+Finally, the keys in the current file are loaded.
+Each time a theme is loaded, the keys are overlaid onto the keys from the previous theme.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+|extends
+|String or Array
+(default: [])
+|extends:
+- default
+- ./brand-theme.yml
+|===
+
 [#keys-page]
 === Page
 
@@ -891,17 +946,25 @@ See <<Title Page>> for details.
 
 3+|[#key-prefix-page]*Key Prefix:* <<key-prefix-page,page>>
 
-|background_color^[1]^
+|background-color^[1]^
 |<<colors,Color>> +
 (default: #ffffff)
 |page:
-  background_color: #fefefe
+  background-color: #fefefe
+
+|background-image^[1]^
+|image macro^[2]^ +
+(default: _not set_)
+|page:
+  background-image: image:page-bg.png[]
 
-|background_image^[1]^
-|Inline image macro^[2]^ +
+|background-image-(recto{vbar}verso)^[1]^
+|image macro^[2]^ +
 (default: _not set_)
 |page:
-  background_image: image:page-bg.png[]
+  background-image:
+    recto: image:page-bg-recto.png[]
+    verso: image:page-bg-verso.png[]
 
 |layout
 |portrait {vbar} landscape +
@@ -915,33 +978,38 @@ See <<Title Page>> for details.
 |page:
   margin: [0.5in, 0.67in, 1in, 0.67in]
 
-|margin_inner^[3]^
+|margin-inner^[3]^
 |<<measurement-units,Measurement>> +
 (default: 48)
 |page:
-  margin_inner: 0.75in
+  margin-inner: 0.75in
 
-|margin_outer^[3]^
+|margin-outer^[3]^
 |<<measurement-units,Measurement>> +
 (default: 24)
 |page:
-  margin_outer: 0.59in
+  margin-outer: 0.59in
 
 |size
 |https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[Named size^] {vbar} <<measurement-units,Measurement[width,height]>> +
 (default: A4)
 |page:
   size: Letter
+
+|numbering-start-at
+|title {vbar} toc {vbar} body +
+(default: body)
+|page:
+  numbering-start-at: toc
 |===
 
-. Page background images are automatically scaled to fit within the bounds of the page.
-+
-NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
-This limitation is due to a bug in Prawn 1.3.1.
-The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
-For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
-. Target may be an absolute path or a path relative to the value of the `pdf-stylesdir` attribute.
-. The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin_inner and margin_outer values.
+. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
+The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background is specified, it will be used only for that side.
+If you flatten out the keys (e.g., `page-background-recto`), you can also set the default page background image (`page-background`), which will then be used as a fallback if a background image isn't specified for a side.
+To disable the background for a side, use the value `none`.
+. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
+. The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin-inner and margin-outer values.
 These margins and used when the value `prepress` is assigned to the `media` document attribute.
 
 [#keys-base]
@@ -950,7 +1018,7 @@ These margins and used when the value `prepress` is assigned to the `media` docu
 The keys in this category provide generic theme settings and are often referenced throughout the theme file as variables.
 We recommended that you define this category after the page category and before all other categories.
 
-NOTE: While it's common to define additional keys in this category (e.g., `base_border_radius`) to keep your theme DRY, we recommend using <<Custom Variables,custom variables>> instead.
+NOTE: While it's common to define additional keys in this category (e.g., `base-border-radius`) to keep your theme DRY, we recommend using <<Custom Variables,custom variables>> instead.
 
 [cols="3,4,5l"]
 |===
@@ -964,92 +1032,92 @@ NOTE: While it's common to define additional keys in this category (e.g., `base_
 |base:
   align: justify
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: #eeeeee)
 |base:
-  border_color: #eeeeee
+  border-color: #eeeeee
 
-// border_radius is variable, not an official key
-//|border_radius
+// border-radius is variable, not an official key
+//|border-radius
 //|<<values,Number>>
 //|base:
-//  border_radius: 4
+//  border-radius: 4
 
-|border_width
+|border-width
 |<<values,Number>> +
 (default: 0.5)
 |base:
-  border_width: 0.5
+  border-width: 0.5
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: #000000)
 |base:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: Helvetica)
 |base:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 12)
 |base:
-  font_size: 10.5
+  font-size: 10.5
 
-// font_size_large is a variable, not an official key
-//|font_size_large
+// font-size-large is a variable, not an official key
+//|font-size-large
 //|<<values,Number>>
 //|base:
-//  font_size_large: 13
+//  font-size-large: 13
 
-|font_size_min
+|font-size-min
 |<<values,Number>> +
 (default: 9)
 |base:
-  font_size_min: 6
+  font-size-min: 6
 
-// font_size_small is a variable, not an official key
-//|font_size_small
+// font-size-small is a variable, not an official key
+//|font-size-small
 //|<<values,Number>>
 //|base:
-//  font_size_small: 9
+//  font-size-small: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: normal)
 |base:
-  font_style: normal
+  font-style: normal
 
-|text_transform^[1]^
+|text-transform^[1]^
 |none +
 (default: none)
 |base:
-  text_transform: none
+  text-transform: none
 
-|line_height_length^[2]^
+|line-height-length^[2]^
 |<<values,Number>> +
 (default: 13.8)
 |base:
-  line_height_length: 12
+  line-height-length: 12
 
-|line_height^[2]^
+|line-height^[2]^
 |<<values,Number>> +
 (default: 1.15)
 |base:
-  line_height: >
-    $base_line_height_length /
-    $base_font_size
+  line-height: >
+    $base-line-height-length /
+    $base-font-size
 |===
 
-. The `text_transform` key cannot be set globally.
+. The `text-transform` key cannot be set globally.
 Therefore, this key should not be used.
 The value of `none` is implicit and is documented here for completeness.
-. You should set one of `line_height` or `line_height_length`, then derive the value of the other using a calculation as these are correlated values.
-For instance, if you set `line_height_length`, then use `$base_line_height_length / $base_font_size` as the value of `line_height`.
+. You should set one of `line-height` or `line-height-length`, then derive the value of the other using a calculation as these are correlated values.
+For instance, if you set `line-height-length`, then use `$base-line-height-length / $base-font-size` as the value of `line-height`.
 
 [#keys-vertical-spacing]
 === Vertical Spacing
@@ -1060,10 +1128,10 @@ The keys in this category control the general spacing between elements where a m
 |===
 |Key |Value Type |Example
 
-|vertical_spacing
+|vertical-spacing
 |<<values,Number>> +
 (default: 12)
-|vertical_spacing: 10
+|vertical-spacing: 10
 |===
 
 [#keys-link]
@@ -1077,35 +1145,35 @@ The keys in this category are used to style hyperlink text.
 
 3+|[#key-prefix-link]*Key Prefix:* <<key-prefix-link,link>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: #0000ee)
 |link:
-  font_color: #428bca
+  font-color: #428bca
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |link:
-  font_family: Roboto
+  font-family: Roboto
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |link:
-  font_size: 9
+  font-size: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |link:
-  font_style: italic
+  font-style: italic
 
-|text_decoration
+|text-decoration
 |none {vbar} underline {vbar} line-through +
 (default: none)
 |link:
-  text_decoration: underline
+  text-decoration: underline
 |===
 
 [#keys-literal]
@@ -1119,29 +1187,29 @@ The keys in this category are used for inline monospaced text in prose and table
 
 3+|[#key-prefix-literal]*Key Prefix:* <<key-prefix-literal,literal>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |literal:
-  font_color: #b12146
+  font-color: #b12146
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: Courier)
 |literal:
-  font_family: M+ 1mn
+  font-family: M+ 1mn
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |literal:
-  font_size: 12
+  font-size: 12
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |literal:
-  font_style: bold
+  font-style: bold
 |===
 
 [#keys-heading]
@@ -1157,96 +1225,96 @@ The keys in this category control the style of most headings, including part tit
 
 |align
 |<<text-alignments,Text alignment>> +
-(default: $base_align)
+(default: $base-align)
 |heading:
   align: center
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |heading:
-  font_color: #222222
+  font-color: #222222
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $base_font_family)
+(default: $base-font-family)
 |heading:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-// NOTE: heading_font_size is overridden by h<n>_font_size in base theme
-//|font_size
+// NOTE: heading-font-size is overridden by h<n>-font-size in base theme
+//|font-size
 //|<<values,Number>> +
-//(default: $base_font_size)
+//(default: $base-font-size)
 //|heading:
-//  font_size: 18
+//  font-size: 18
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |heading:
-  font_style: bold
+  font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |heading:
-  text_transform: uppercase
+  text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.15)
 |heading:
-  line_height: 1.2
+  line-height: 1.2
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 4)
 |heading:
-  margin_top: $vertical_spacing * 0.2
+  margin-top: $vertical-spacing * 0.2
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |heading:
-  margin_bottom: 9.6
+  margin-bottom: 9.6
 
-3+|[#key-prefix-heading-level]*Key Prefix:* <<key-prefix-heading-level,heading_h<n> >>^[1]^
+3+|[#key-prefix-heading-level]*Key Prefix:* <<key-prefix-heading-level,heading-h<n> >>^[1]^
 
 |align
 |<<text-alignments,Text alignment>> +
-(default: $heading_align)
+(default: $heading-align)
 |heading:
-  h2_align: center
+  h2-align: center
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $heading_font_color)
+(default: $heading-font-color)
 |heading:
-  h2_font_color: [0, 99%, 100%, 0]
+  h2-font-color: [0, 99%, 100%, 0]
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $heading_font_family)
+(default: $heading-font-family)
 |heading:
-  h4_font_family: Roboto
+  h4-font-family: Roboto
 
-|font_size^[1]^
+|font-size^[1]^
 |<<values,Number>> +
 (default: <1>=24; <2>=18; <3>=16; <4>=14; <5>=12; <6>=10)
 |heading:
-  h6_font_size: $base_font_size * 1.7
+  h6-font-size: $base-font-size * 1.7
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
-(default: $heading_font_style)
+(default: $heading-font-style)
 |heading:
-  h3_font_style: bold_italic
+  h3-font-style: bold_italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
-(default: $heading_text_transform)
+(default: $heading-text-transform)
 |heading:
-  text_transform: lowercase
+  text-transform: lowercase
 |===
 
 . `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
@@ -1264,332 +1332,328 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-title-page]*Key Prefix:* <<key-prefix-title-page,title_page>>
+3+|[#key-prefix-title-page]*Key Prefix:* <<key-prefix-title-page,title-page>>
 
 |align
 |<<text-alignments,Text alignment>> +
 (default: center)
-|title_page:
+|title-page:
   align: right
 
-|background_color^[1]^
+|background-color^[1]^
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
-  background_color: #eaeaea
+|title-page:
+  background-color: #eaeaea
 
-|background_image^[1]^
-|Inline image macro^[2]^ +
+|background-image^[1]^
+|image macro^[2]^ +
 (default: _not set_)
-|title_page:
-  background_image: image:title.png[]
+|title-page:
+  background-image: image:title.png[]
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
-  font_color: #333333
+|title-page:
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
-|title_page:
-  font_family: Noto Serif
+|title-page:
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
-|title_page:
-  font_size: 13
+|title-page:
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|title_page:
-  font_style: bold
+|title-page:
+  font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
-|title_page:
-  text_transform: uppercase
+|title-page:
+  text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.15)
-|title_page:
-  line_height: 1
+|title-page:
+  line-height: 1
 
-3+|[#key-prefix-title-page-logo]*Key Prefix:* <<key-prefix-title-page-logo,title_page_logo>>
+3+|[#key-prefix-title-page-logo]*Key Prefix:* <<key-prefix-title-page-logo,title-page-logo>>
 
 |align
 |<<image-alignments,Image alignment>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   logo:
     align: right
 
 |image
-|Inline image macro^[2]^ +
+|image macro^[2]^ +
 (default: _not set_)
-|title_page:
+|title-page:
   logo:
     image: image:logo.png[pdfwidth=25%]
 
 |top
 |Percentage^[3]^ +
 (default: 10%)
-|title_page:
+|title-page:
   logo:
     top: 25%
 
-3+|[#key-prefix-title-page-title]*Key Prefix:* <<key-prefix-title-page-title,title_page_title>>
+3+|[#key-prefix-title-page-title]*Key Prefix:* <<key-prefix-title-page-title,title-page-title>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   title:
-    font_color: #999999
+    font-color: #999999
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   title:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 18)
-|title_page:
+|title-page:
   title:
-    font_size: $heading_h1_font_size
+    font-size: $heading-h1-font-size
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   title:
-    font_style: bold
+    font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   title:
-    text_transform: uppercase
+    text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
-(default: $heading_line_height)
-|title_page:
+(default: $heading-line-height)
+|title-page:
   title:
-    line_height: 0.9
+    line-height: 0.9
 
 |top
 |Percentage^[3]^ +
 (default: 40%)
-|title_page:
+|title-page:
   title:
     top: 55%
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   title:
-    margin_top: 13.125
+    margin-top: 13.125
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   title:
-    margin_bottom: 5
+    margin-bottom: 5
 
-3+|[#key-prefix-title-page-subtitle]*Key Prefix:* <<key-prefix-title-page-subtitle,title_page_subtitle>>
+3+|[#key-prefix-title-page-subtitle]*Key Prefix:* <<key-prefix-title-page-subtitle,title-page-subtitle>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   subtitle:
-    font_color: #181818
+    font-color: #181818
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   subtitle:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 14)
-|title_page:
+|title-page:
   subtitle:
-    font_size: $heading_h3_font_size
+    font-size: $heading-h3-font-size
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   subtitle:
-    font_style: bold_italic
+    font-style: bold_italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   subtitle:
-    text_transform: uppercase
+    text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
-(default: $heading_line_height)
-|title_page:
+(default: $heading-line-height)
+|title-page:
   subtitle:
-    line_height: 1
+    line-height: 1
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   subtitle:
-    margin_top: 13.125
+    margin-top: 13.125
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   subtitle:
-    margin_bottom: 5
+    margin-bottom: 5
 
-3+|[#key-prefix-authors]*Key Prefix:* <<key-prefix-authors,title_page_authors>>
+3+|[#key-prefix-authors]*Key Prefix:* <<key-prefix-authors,title-page-authors>>
 
 |delimiter
 |<<quoted-string,Quoted string>> +
 (default: ', ')
-|title_page:
+|title-page:
   authors:
     delimiter: '; '
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   authors:
-    font_color: #181818
+    font-color: #181818
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   authors:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   authors:
-    font_size: 13
+    font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   authors:
-    font_style: bold_italic
+    font-style: bold_italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   authors:
-    text_transform: uppercase
+    text-transform: uppercase
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 12)
-|title_page:
+|title-page:
   authors:
-    margin_top: 13.125
+    margin-top: 13.125
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   authors:
-    margin_bottom: 5
+    margin-bottom: 5
 
-3+|[#key-prefix-revision]*Key Prefix:* <<key-prefix-revision,title_page_revision>>
+3+|[#key-prefix-revision]*Key Prefix:* <<key-prefix-revision,title-page-revision>>
 
 |delimiter
 |<<quoted-string,Quoted string>> +
 (default: ', ')
-|title_page:
+|title-page:
   revision:
     delimiter: ': '
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   revision:
-    font_color: #181818
+    font-color: #181818
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   revision:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   revision:
-    font_size: $base_font_size_small
+    font-size: $base-font-size-small
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   revision:
-    font_style: bold
+    font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
-|title_page:
+|title-page:
   revision:
-    text_transform: uppercase
+    text-transform: uppercase
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   revision:
-    margin_top: 13.125
+    margin-top: 13.125
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 0)
-|title_page:
+|title-page:
   revision:
-    margin_bottom: 5
+    margin-bottom: 5
 |===
 
-. Page background images are automatically scaled to fit within the bounds of the page.
-+
-NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
-This limitation is due to a bug in Prawn 1.3.1.
-The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
-For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
-. Target may be an absolute path or a path relative to the value of the `pdf-stylesdir` attribute.
+. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
+The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+. Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
 . Percentage unit can be % (relative to content height) or vh (relative to page height).
 
 [#keys-prose]
@@ -1604,19 +1668,34 @@ Typically, all the margin is placed on the bottom.
 
 3+|[#key-prefix-prose]*Key Prefix:* <<key-prefix-prose,prose>>
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
 |prose:
-  margin_top: 0
+  margin-top: 0
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |prose:
-  margin_bottom: $vertical_spacing
+  margin-bottom: $vertical-spacing
+
+|margin-inner^[1]^
+|<<measurement-units,Measurement>> +
+(default: $prose-margin-bottom)
+|prose:
+  margin-inner: 0
+
+|text-indent
+|<<measurement-units,Measurement>> +
+(default: _not set_)
+|prose:
+  text-indent: 18
 |===
 
+. Controls the margin between adjacent paragraphs.
+Useful when using indented paragraphs.
+
 [#keys-block]
 === Block
 
@@ -1633,17 +1712,17 @@ The keys in this category control the spacing around block elements when a more
 //|block:
 //  padding: [12, 15, 12, 15]
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
 |block:
-  margin_top: 6
+  margin-top: 6
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
 (default: 12)
 |block:
-  margin_bottom: 6
+  margin-bottom: 6
 |===
 
 Block styles are applied to the following block types:
@@ -1681,47 +1760,47 @@ The keys in this category control the arrangement and style of block captions.
 |caption:
   align: left
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |caption:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |caption:
-  font_family: M+ 1mn
+  font-family: M+ 1mn
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |caption:
-  font_size: 11
+  font-size: 11
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: italic)
 |caption:
-  font_style: italic
+  font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |caption:
-  text_transform: uppercase
+  text-transform: uppercase
 
-|margin_inside
+|margin-inside
 |<<measurement-units,Measurement>> +
 (default: 4)
 |caption:
-  margin_inside: 3
+  margin-inside: 3
 
-|margin_outside
+|margin-outside
 |<<measurement-units,Measurement>> +
 (default: 0)
 |caption:
-  margin_outside: 0
+  margin-outside: 0
 |===
 
 [#keys-code]
@@ -1735,65 +1814,65 @@ The keys in this category are used to control the style of literal, listing and
 
 3+|[#key-prefix-code]*Key Prefix:* <<key-prefix-code,code>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
 (default: _not set_)
 |code:
-  background_color: #f5f5f5
+  background-color: #f5f5f5
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: #eeeeee)
 |code:
-  border_color: #cccccc
+  border-color: #cccccc
 
-|border_radius
+|border-radius
 |<<values,Number>> +
 (default: _not set_)
 |code:
-  border_radius: 4
+  border-radius: 4
 
-|border_width
+|border-width
 |<<values,Number>> +
 (default: 0.5)
 |code:
-  border_width: 0.75
+  border-width: 0.75
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |code:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: Courier)
 |code:
-  font_family: M+ 1mn
+  font-family: M+ 1mn
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 10.5)
 |code:
-  font_size: 11
+  font-size: 11
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |code:
-  font_style: italic
+  font-style: italic
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.2)
 |code:
-  line_height: 1.25
+  line-height: 1.25
 
-|line_gap^[1]^
+|line-gap^[1]^
 |<<values,Number>> +
 (default: 0)
 |code:
-  line_gap: 3.8
+  line-gap: 3.8
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -1801,16 +1880,16 @@ The keys in this category are used to control the style of literal, listing and
 |code:
   padding: 11
 
-3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-code-linenum,code_linenum>>^[2]^
+3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-code-linenum,code-linenum>>^[2]^
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: #999999)
 |code:
-  linenum_font_color: #ccc
+  linenum-font-color: #ccc
 |===
-. The line_gap is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
-. The code_linenum category only applies when using Pygments as the source highlighter.
+. The line-gap property is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
+. The code-linenum category only applies when using Pygments as the source highlighter.
 Otherwise, the style is controlled by the source highlighter theme.
 
 [#keys-callout-numbers]
@@ -1824,39 +1903,39 @@ The keys in this category are used to control the style of callout numbers (conu
 
 3+|[#key-prefix-conum]*Key Prefix:* <<key-prefix-conum,conum>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |conum:
-  font_color: #b12146
+  font-color: #b12146
 
-|font_family^[1,2]^
+|font-family^[1,2]^
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |conum:
-  font_family: M+ 1mn
+  font-family: M+ 1mn
 
-|font_size^[2]^
+|font-size^[2]^
 |<<values,Number>> +
 (default: _inherit_)
 |conum:
-  font_size: $base_font_size
+  font-size: $base-font-size
 
-|font_style^[2]^
+|font-style^[2]^
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |conum:
-  font_style: normal
+  font-style: normal
 
-|line_height^[2]^
+|line-height^[2]^
 |<<values,Number>> +
 (default: 1.15)
 |conum:
-  line_height: 4 / 3
+  line-height: 4 / 3
 |===
 
 . Currently, the font must contain the circle numbers starting at glyph U+2460.
-. font_family, font_size, font_style, and line_height are only used for markers in a colist.
+. font-family, font-size, font-style, and line-height are only used for markers in a colist.
 These properties are inherited for conums inside a verbatim block.
 
 [#keys-menu]
@@ -1870,11 +1949,11 @@ The keys in this category apply to the menu label (generated from the inline men
 
 3+|[#key-prefix-menu]*Key Prefix:* <<key-prefix-menu,menu>>
 
-|caret_content
+|caret-content
 |<<quoted-string,Quoted string>> +
 (default: " \u203a ")
 |menu:
-  caret_content: ' > '
+  caret-content: ' > '
 |===
 
 [#keys-blockquote]
@@ -1888,47 +1967,47 @@ The keys in this category control the arrangement and style of quote blocks.
 
 3+|[#key-prefix-blockquote]*Key Prefix:* <<key-prefix-blockquote,blockquote>>
 
-|border_width^[1]^
+|border-width^[1]^
 |<<values,Number>> +
 (default: 4)
 |blockquote:
-  border_width: 5
+  border-width: 5
 
-|border_color^[1]^
+|border-color^[1]^
 |<<colors,Color>> +
 (default: #eeeeee)
 |blockquote:
-  border_color: #eeeeee
+  border-color: #eeeeee
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |blockquote:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |blockquote:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |blockquote:
-  font_size: 13
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |blockquote:
-  font_style: bold
+  font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |blockquote:
-  text_transform: uppercase
+  text-transform: uppercase
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -1936,42 +2015,42 @@ The keys in this category control the arrangement and style of quote blocks.
 |blockquote:
   padding: [5, 10, -5, 12]
 
-3+|[#key-prefix-blockquote-cite]*Key Prefix:* <<key-prefix-blockquote-cite,blockquote_cite>>
+3+|[#key-prefix-blockquote-cite]*Key Prefix:* <<key-prefix-blockquote-cite,blockquote-cite>>
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |blockquote:
   cite:
-    font_size: 9
+    font-size: 9
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |blockquote:
   cite:
-    font_color: #999999
+    font-color: #999999
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |blockquote:
   cite:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |blockquote:
   cite:
-    font_style: bold
+    font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |blockquote:
   cite:
-    text_transform: uppercase
+    text-transform: uppercase
 |===
 
 . Only applies to the left side.
@@ -1987,59 +2066,59 @@ The keys in this category control the arrangement and style of sidebar blocks.
 
 3+|[#key-prefix-sidebar]*Key Prefix:* <<key-prefix-sidebar,sidebar>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
 (default: #eeeeee)
 |sidebar:
-  background_color: #eeeeee
+  background-color: #eeeeee
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: _not set_)
 |sidebar:
-  border_color: #ffffff
+  border-color: #ffffff
 
-|border_radius
+|border-radius
 |<<values,Number>> +
 (default: _not set_)
 |sidebar:
-  border_radius: 4
+  border-radius: 4
 
-|border_width
+|border-width
 |<<values,Number>> +
 (default: _not set_)
 |sidebar:
-  border_width: 0.5
+  border-width: 0.5
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |sidebar:
-  font_color: #262626
+  font-color: #262626
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |sidebar:
-  font_family: M+ 1p
+  font-family: M+ 1p
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |sidebar:
-  font_size: 13
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |sidebar:
-  font_style: italic
+  font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |sidebar:
-  text_transform: uppercase
+  text-transform: uppercase
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -2047,7 +2126,7 @@ The keys in this category control the arrangement and style of sidebar blocks.
 |sidebar:
   padding: [12, 15, 0, 15]
 
-3+|[#key-prefix-sidebar-title]*Key Prefix:* <<key-prefix-sidebar-title,sidebar_title>>
+3+|[#key-prefix-sidebar-title]*Key Prefix:* <<key-prefix-sidebar-title,sidebar-title>>
 
 |align
 |<<text-alignments,Text alignment>> +
@@ -2056,40 +2135,40 @@ The keys in this category control the arrangement and style of sidebar blocks.
   title:
     align: center
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |sidebar:
   title:
-    font_color: #333333
+    font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |sidebar:
   title:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |sidebar:
   title:
-    font_size: 13
+    font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |sidebar:
   title:
-    font_style: bold
+    font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |sidebar:
   title:
-    text_transform: uppercase
+    text-transform: uppercase
 |===
 
 [#keys-example]
@@ -2103,59 +2182,59 @@ The keys in this category control the arrangement and style of example blocks.
 
 3+|[#key-prefix-example]*Key Prefix:* <<key-prefix-example,example>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
 (default: #ffffff)
 |example:
-  background_color: #fffef7
+  background-color: #fffef7
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: #eeeeee)
 |example:
-  border_color: #eeeeee
+  border-color: #eeeeee
 
-|border_radius
+|border-radius
 |<<values,Number>> +
 (default: _not set_)
 |example:
-  border_radius: 4
+  border-radius: 4
 
-|border_width
+|border-width
 |<<values,Number>> +
 (default: 0.5)
 |example:
-  border_width: 0.75
+  border-width: 0.75
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |example:
-  font_color: #262626
+  font-color: #262626
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |example:
-  font_family: M+ 1p
+  font-family: M+ 1p
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |example:
-  font_size: 13
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |example:
-  font_style: italic
+  font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |example:
-  text_transform: uppercase
+  text-transform: uppercase
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -2175,53 +2254,53 @@ The keys in this category control the arrangement and style of admonition blocks
 
 3+|[#key-prefix-admonition]*Key Prefix:* <<key-prefix-admonition,admonition>>
 
-|column_rule_color
+|column-rule-color
 |<<colors,Color>> +
 (default: #eeeeee)
 |admonition:
-  column_rule_color: #aa0000
+  column-rule-color: #aa0000
 
-|column_rule_style
+|column-rule-style
 |solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
 |admonition:
-  column_rule_style: double
+  column-rule-style: double
 
-|column_rule_width
+|column-rule-width
 |<<values,Number>> +
 (default: 0.5)
 |admonition:
-  column_rule_width: 0.5
+  column-rule-width: 0.5
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |admonition:
-  font_color: #999999
+  font-color: #999999
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |admonition:
-  font_family: Noto Sans
+  font-family: Noto Sans
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |admonition:
-  font_size: $base_font_size_large
+  font-size: $base-font-size-large
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |admonition:
-  font_style: italic
+  font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |admonition:
-  text_transform: none
+  text-transform: none
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -2229,7 +2308,7 @@ The keys in this category control the arrangement and style of admonition blocks
 |admonition:
   padding: [0, 12, 0, 12]
 
-3+|[#key-prefix-admonition-label]*Key Prefix:* <<key-prefix-admonition-label,admonition_label>>
+3+|[#key-prefix-admonition-label]*Key Prefix:* <<key-prefix-admonition-label,admonition-label>>
 
 |align
 |<<text-alignments,Text alignment>> +
@@ -2238,64 +2317,64 @@ The keys in this category control the arrangement and style of admonition blocks
   label:
     align: center
 
-|min_width
+|min-width
 |<<measurement-units,Measurement>> +
 (default: _not set_)
 |admonition:
   label:
-    min_width: 48
+    min-width: 48
 
 |padding^[1]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
-(default: $admonition_padding)
+(default: $admonition-padding)
 |admonition:
   padding: [0, 12, 0, 12]
 
-|vertical_align
+|vertical-align
 |top {vbar} middle {vbar} bottom +
 (default: middle)
 |admonition:
   label:
-    vertical_align: top
+    vertical-align: top
 
-3+|*Key Prefix:* admonition_label, admonition_label_<name>^[2]^
+3+|*Key Prefix:* admonition-label, admonition-label-<name>^[2]^
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |admonition:
   label:
-    font_color: #262626
+    font-color: #262626
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |admonition:
   label:
-    font_family: M+ 1p
+    font-family: M+ 1p
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |admonition:
   label:
-    font_size: 12
+    font-size: 12
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |admonition:
   label:
-    font_style: bold_italic
+    font-style: bold_italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: uppercase)
 |admonition:
   label:
-    text_transform: lowercase
+    text-transform: lowercase
 
-3+|[#key-prefix-admonition-icon]*Key Prefix:* <<key-prefix-admonition-icon,admonition_icon_<name> >>^[2]^
+3+|[#key-prefix-admonition-icon]*Key Prefix:* <<key-prefix-admonition-icon,admonition-icon-<name> >>^[2]^
 
 |name
 |<icon set>-<icon name>^[3]^ +
@@ -2305,13 +2384,13 @@ The keys in this category control the arrangement and style of admonition blocks
     tip:
       name: fas-fire
 
-|stroke_color
+|stroke-color
 |<<colors,Color>> +
 (default: caution=#bf3400; important=#bf0000; note=#19407c; tip=#111111; warning=#bf6900)
 |admonition:
   icon:
     important:
-      stroke_color: ff0000
+      stroke-color: ff0000
 
 |size
 |<<values,Number>> +
@@ -2322,9 +2401,9 @@ The keys in this category control the arrangement and style of admonition blocks
       size: 24
 |===
 
-. The top and bottom padding values are ignored on admonition_label_padding.
+. The top and bottom padding values are ignored on admonition-label-padding.
 . `<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.
-The subkeys in the icon category cannot be flattened (e.g., `tip_name: far-lightbulb` is not valid syntax).
+The subkeys in the icon category cannot be flattened (e.g., `tip-name: far-lightbulb` is not valid syntax).
 . Required.
 See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository] for a list of valid icon names.
 The prefix (e.g., `fas-`) determines which font set to use.
@@ -2367,41 +2446,41 @@ The keys in this category control the styling of lead paragraphs.
 
 3+|[#key-prefix-lead]*Key Prefix:* <<key-prefix-lead,lead>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |lead:
-  font_color: #262626
+  font-color: #262626
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |lead:
-  font_family: M+ 1p
+  font-family: M+ 1p
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 13.5)
 |lead:
-  font_size: 13
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |lead:
-  font_style: bold
+  font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |lead:
-  text_transform: uppercase
+  text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.4)
 |lead:
-  line_height: 1.4
+  line-height: 1.4
 |===
 
 [#keys-abstract]
@@ -2415,35 +2494,35 @@ The keys in this category control the arrangement and style of the abstract.
 
 3+|[#key-prefix-abstract]*Key Prefix:* <<key-prefix-abstract,abstract>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $base_font_color)
+(default: $base-font-color)
 |abstract:
-  font_color: #5c6266
+  font-color: #5c6266
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: 13.5)
 |abstract:
-  font_size: 13
+  font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
-(default: $base_font_style)
+(default: $base-font-style)
 |abstract:
-  font_style: italic
+  font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
-(default: $base_text_transform)
+(default: $base-text-transform)
 |abstract:
-  text_transform: uppercase
+  text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.4)
 |abstract:
-  line_height: 1.4
+  line-height: 1.4
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -2451,7 +2530,7 @@ The keys in this category control the arrangement and style of the abstract.
 |abstract:
   padding: [0, 12, 0, 12]
 
-3+|[#key-prefix-abstract-title]*Key Prefix:* <<key-prefix-abstract-title,abstract_title>>
+3+|[#key-prefix-abstract-title]*Key Prefix:* <<key-prefix-abstract-title,abstract-title>>
 
 |align
 |<<text-alignments,Text alignment>> +
@@ -2460,40 +2539,40 @@ The keys in this category control the arrangement and style of the abstract.
   title:
     align: center
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $base_font_color)
+(default: $base-font-color)
 |abstract:
   title:
-    font_color: #333333
+    font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $base_font_family)
+(default: $base-font-family)
 |abstract:
   title:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
-(default: $base_font_size)
+(default: $base-font-size)
 |abstract:
   title:
-    font_size: 13
+    font-size: 13
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |abstract:
   title:
-    font_style: bold
+    font-style: bold
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
-(default: $base_text_transform)
+(default: $base-text-transform)
 |abstract:
   title:
-    text_transform: uppercase
+    text-transform: uppercase
 |===
 
 [#keys-thematic-break]
@@ -2505,37 +2584,37 @@ The keys in this category control the style of thematic breaks (aka horizontal r
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-thematic-break]*Key Prefix:* <<key-prefix-thematic-break,thematic_break>>
+3+|[#key-prefix-thematic-break]*Key Prefix:* <<key-prefix-thematic-break,thematic-break>>
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: #eeeeee)
-|thematic_break:
-  border_color: #eeeeee
+|thematic-break:
+  border-color: #eeeeee
 
-|border_style
+|border-style
 |solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
-|thematic_break:
-  border_style: dashed
+|thematic-break:
+  border-style: dashed
 
-|border_width
+|border-width
 |<<measurement-units,Measurement>> +
 (default: 0.5)
-|thematic_break:
-  border_width: 0.5
+|thematic-break:
+  border-width: 0.5
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
-|thematic_break:
-  margin_top: 6
+|thematic-break:
+  margin-top: 6
 
-|margin_bottom
+|margin-bottom
 |<<measurement-units,Measurement>> +
-(default: $vertical_spacing)
-|thematic_break:
-  margin_bottom: 18
+(default: $vertical-spacing)
+|thematic-break:
+  margin-bottom: 18
 |===
 
 [#keys-description-list]
@@ -2547,25 +2626,25 @@ The keys in this category control the arrangement and style of definition list i
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-description-list]*Key Prefix:* <<key-prefix-description-list,description_list>>
+3+|[#key-prefix-description-list]*Key Prefix:* <<key-prefix-description-list,description-list>>
 
-|term_font_style
+|term-font-style
 |<<font-styles,Font style>> +
 (default: bold)
-|description_list:
-  term_font_style: italic
+|description-list:
+  term-font-style: italic
 
-|term_spacing
+|term-spacing
 |<<measurement-units,Measurement>> +
 (default: 4)
-|description_list:
-  term_spacing: 5
+|description-list:
+  term-spacing: 5
 
-|description_indent
+|description-indent
 |<<values,Number>> +
 (default: 30)
-|description_list:
-  description_indent: 15
+|description-list:
+  description-indent: 15
 |===
 
 [#keys-outline-list]
@@ -2577,31 +2656,31 @@ The keys in this category control the arrangement and style of outline list item
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-outline-list]*Key Prefix:* <<key-prefix-outline-list,outline_list>>
+3+|[#key-prefix-outline-list]*Key Prefix:* <<key-prefix-outline-list,outline-list>>
 
 |indent
 |<<measurement-units,Measurement>> +
 (default: 30)
-|outline_list:
+|outline-list:
   indent: 40
 
-|item_spacing
+|item-spacing
 |<<measurement-units,Measurement>> +
 (default: 6)
-|outline_list:
-  item_spacing: 4
+|outline-list:
+  item-spacing: 4
 
-|marker_font_color^[1]^
+|marker-font-color^[1]^
 |<<colors,Color>> +
 (default: _inherit_)
-|outline_list:
-  marker_font_color: #3c763d
+|outline-list:
+  marker-font-color: #3c763d
 
-|text_align^[2]^
+|text-align^[2]^
 |<<text-alignments,Text alignment>> +
-(default: $base_align)
-|outline_list:
-  text_align: left
+(default: $base-align)
+|outline-list:
+  text-align: left
 |===
 
 . Controls the color of the bullet glyph that marks items in unordered lists and the number for items in ordered lists.
@@ -2616,42 +2695,42 @@ The keys in this category control the arrangement and style of unordered list it
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-ulist-marker]*Key Prefix:* <<key-prefix-ulist-marker,ulist_marker>>
+3+|[#key-prefix-ulist-marker]*Key Prefix:* <<key-prefix-ulist-marker,ulist-marker>>
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |ulist:
   marker:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |ulist:
   marker:
-    font_size: 9
+    font-size: 9
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $outline_list_marker_font_color)
+(default: $outline-list-marker-font-color)
 |ulist:
   marker:
-    font_color: #cccccc
+    font-color: #cccccc
 
-|line_height
+|line-height
 |<<values,Number>> +
-(default: $base_line_height)
+(default: $base-line-height)
 |ulist:
   marker:
-    line_height: 1.5
+    line-height: 1.5
 |===
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|*Key Prefix:* ulist_marker_<type>^[1]^
+3+|*Key Prefix:* ulist-marker-<type>^[1]^
 
 |content
 |<<quoted-string,Quoted string>>
@@ -2660,37 +2739,37 @@ The keys in this category control the arrangement and style of unordered list it
     disc:
       content: "\uf140"
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |ulist:
   marker:
     disc:
-      font_family: fas
+      font-family: fas
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |ulist:
   marker:
     disc:
-      font_size: 9
+      font-size: 9
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |ulist:
   marker:
     disc:
-      font_color: #ff0000
+      font-color: #ff0000
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: _inherit_)
 |ulist:
   marker:
     disc:
-      line_height: 2
+      line-height: 2
 |===
 
 . <type> is one of disc, square, circle, checked, unchecked
@@ -2706,79 +2785,85 @@ The keys in this category control the arrangement and style of tables and table
 
 3+|[#key-prefix-table]*Key Prefix:* <<key-prefix-table,table>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
 (default: transparent)
 |table:
-  background_color: #ffffff
+  background-color: #ffffff
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: #000000)
 |table:
-  border_color: #dddddd
+  border-color: #dddddd
 
-|border_style
+|border-style
 |solid {vbar} dashed {vbar} dotted +
 (default: solid)
 |table:
-  border_style: solid
+  border-style: solid
 
-|border_width
+|border-width
 |<<values,Number>> +
 (default: 0.5)
 |table:
-  border_width: 0.5
+  border-width: 0.5
 
-|caption_side
+|caption-side
 |top {vbar} bottom +
 (default: top)
 |table:
-  caption_side: bottom
+  caption-side: bottom
 
-|font_color
+|caption-max-width
+|fit-content {vbar} none +
+(default: fit-content)
+|table:
+  caption-max-width: none
+
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |table:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |table:
-  font_family: Helvetica
+  font-family: Helvetica
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |table:
-  font_size: 9.5
+  font-size: 9.5
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |table:
-  font_style: italic
+  font-style: italic
 
-|grid_color
+|grid-color
 |<<colors,Color>> +
-(default: $table_border_color)
+(default: $table-border-color)
 |table:
-  grid_color: #eeeeee
+  grid-color: #eeeeee
 
-|grid_style
+|grid-style
 |solid {vbar} dashed {vbar} dotted +
 (default: solid)
 |table:
-  grid_style: dashed
+  grid-style: dashed
 
-|grid_width
+|grid-width
 |<<values,Number>> +
-(default: $table_border_width)
+(default: $table-border-width)
 |table:
-  grid_width: 0.5
+  grid-width: 0.5
 
-3+|[#key-prefix-table-head]*Key Prefix:* <<key-prefix-table-head,table_head>>
+3+|[#key-prefix-table-head]*Key Prefix:* <<key-prefix-table-head,table-head>>
 
 //|align
 //|<<text-alignments,Text alignment>> +
@@ -2787,112 +2872,123 @@ The keys in this category control the arrangement and style of tables and table
 //  head:
 //    align: center
 
-|background_color
+|background-color
 |<<colors,Color>> +
-(default: $table_background_color)
+(default: $table-background-color)
 |table:
   head:
-    background_color: #f0f0f0
+    background-color: #f0f0f0
 
-|font_color
+|border-bottom-color
 |<<colors,Color>> +
-(default: $table_font_color)
+(default: $table-border-color)
 |table:
   head:
-    font_color: #333333
+    border-bottom-color: #dddddd
 
-|font_family
+|border-bottom-style
+|solid {vbar} dashed {vbar} dotted +
+(default: solid)
+|table:
+  head:
+    border-bottom-style: dashed
+
+|border-bottom-width
+|<<values,Number>> +
+(default: 1.25)
+|table:
+  head:
+    border-bottom-width: 1
+
+|font-color
+|<<colors,Color>> +
+(default: $table-font-color)
+|table:
+  head:
+    font-color: #333333
+
+|font-family
 |<<fonts,Font family name>> +
-(default: $table_font_family)
+(default: $table-font-family)
 |table:
   head:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
-(default: $table_font_size)
+(default: $table-font-size)
 |table:
   head:
-    font_size: 10
+    font-size: 10
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: bold)
 |table:
   head:
-    font_style: normal
+    font-style: normal
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |table:
   head:
-    text_transform: uppercase
+    text-transform: uppercase
 
-3+|[#key-prefix-table-body]*Key Prefix:* <<key-prefix-table-body,table_body>>
+3+|[#key-prefix-table-body]*Key Prefix:* <<key-prefix-table-body,table-body>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
-(default: $table_background_color)
+(default: $table-background-color)
 |table:
   body:
-    background_color: #fdfdfd
+    background-color: #fdfdfd
 
-|stripe_background_color^[1]^
+|stripe-background-color^[1]^
 |<<colors,Color>> +
 (default: #eeeeee)
 |table:
   body:
-    stripe_background_color: #efefef
+    stripe-background-color: #efefef
 
-3+|[#key-prefix-table-foot]*Key Prefix:* <<key-prefix-table-foot,table_foot>>
+3+|[#key-prefix-table-foot]*Key Prefix:* <<key-prefix-table-foot,table-foot>>
 
-|background_color
+|background-color
 |<<colors,Color>> +
-(default: $table_background_color)
+(default: $table-background-color)
 |table:
   foot:
-    background_color: #f0f0f0
+    background-color: #f0f0f0
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $table_font_color)
+(default: $table-font-color)
 |table:
   foot:
-    font_color: #333333
+    font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $table_font_family)
+(default: $table-font-family)
 |table:
   foot:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
-(default: $table_font_size)
+(default: $table-font-size)
 |table:
   foot:
-    font_size: 10
+    font-size: 10
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: normal)
 |table:
   foot:
-    font_style: italic
-
-//deprecated
-//3+|[#key-prefix-table-row]*Key Prefix:* <<key-prefix-table-row,table_<parity>_row>>^[1]^
-//
-//|background_color
-//|<<colors,Color>> +
-//(default: $table_background_color)
-//|table:
-//  even_row:
-//    background_color: #f9f9f9
+    font-style: italic
 
-3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-table-cell,table_cell>>
+3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-table-cell,table-cell>>
 
 |padding
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -2901,59 +2997,112 @@ The keys in this category control the arrangement and style of tables and table
   cell:
     padding: 3
 
-3+|[#key-prefix-table-header-cell]*Key Prefix:* <<key-prefix-table-header-cell,table_header_cell>>
+3+|[#key-prefix-table-header-cell]*Key Prefix:* <<key-prefix-table-header-cell,table-header-cell>>
 
 //|align
 //|<<text-alignments,Text alignment>> +
-//(default: $table_head_align)
+//(default: $table-head-align)
 //|table:
-//  header_cell:
+//  header-cell:
 //    align: center
 
-|background_color
+|background-color
 |<<colors,Color>> +
-(default: $table_head_background_color)
+(default: $table-head-background-color)
 |table:
-  header_cell:
-    background_color: #f0f0f0
+  header-cell:
+    background-color: #f0f0f0
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $table_head_font_color)
+(default: $table-head-font-color)
 |table:
-  header_cell:
-    font_color: #1a1a1a
+  header-cell:
+    font-color: #1a1a1a
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $table_head_font_family)
+(default: $table-head-font-family)
 |table:
-  header_cell:
-    font_family: Noto Sans
+  header-cell:
+    font-family: Noto Sans
 
-|font_size
+|font-size
 |<<values,Number>> +
-(default: $table_head_font_size)
+(default: $table-head-font-size)
 |table:
-  header_cell:
-    font_size: 12
+  header-cell:
+    font-size: 12
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
-(default: $table_head_font_style)
+(default: $table-head-font-style)
 |table:
-  header_cell:
-    font_style: italic
+  header-cell:
+    font-style: italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
-(default: $table_head_text_transform)
+(default: $table-head-text-transform)
 |table:
-  header_cell:
-    text_transform: uppercase
+  header-cell:
+    text-transform: uppercase
+|===
+. This key only controls the color that is used for stripes.
+The appearance of stripes is controlled using the `stripes` table attribute, the `table-stripes` document attribute (since Asciidoctor 2), or the `stripes` document attribute (prior to Asciidoctor 2).
+Permitted attribute values are even, odd, all, and none.
+Prior to Asciidoctor 2, even rows are shaded by default (e.g., `stripes=even`).
+Since Asciidoctor 2, table stripes are not enabled by default (e.g., `stripes=none`).
+
+[#keys-footnotes]
+=== Footnotes
+
+The keys in this catagory control the style the list of footnotes at the end of the chapter (book) or document (otherwise).
+If the `footnotes-title` attribute is specified, it is styled as a block caption.
+The styling of the links is controlled by the global link styles.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-footnotes]*Key Prefix:* <<key-prefix-footnotes,footnotes>>
+
+|font-color
+|<<colors,Color>> +
+(default: $base-font-color)
+|footnotes:
+  font-color: #cccccc
+
+|font-size
+|<<values,Number>> +
+(default: 8)
+|footnotes:
+  font-size: 6
+
+|font-style
+|<<font-styles,Font style>> +
+(default: $base-font-style)
+|footnotes:
+  font-style: italic
+
+|item-spacing
+|<<measurement-units,Measurement>> +
+(default: 3)
+|footnotes:
+  item-spacing: 5
+
+|margin-top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|footnotes:
+  margin-top: 10
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: _inherit_)
+|footnotes:
+  text-transform: lowercase
 |===
-. Applied to even rows by default; controlled using `stripes` attribute (even, odd, all, none) on table.
-//. `<parity>` can be `odd` (odd rows) or `even` (even rows).
 
 [#keys-table-of-contents]
 === Table of Contents (TOC)
@@ -2966,48 +3115,48 @@ The keys in this category control the arrangement and style of the table of cont
 
 3+|[#key-prefix-toc]*Key Prefix:* <<key-prefix-toc,toc>>
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |toc:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |toc:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |toc:
-  font_size: 9
+  font-size: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 // QUESTION why is the default not inherited?
 (default: normal)
 |toc:
-  font_style: bold
+  font-style: bold
 
-|text_decoration
+|text-decoration
 |none {vbar} underline +
 (default: none)
 |toc:
-  text_decoration: underline
+  text-decoration: underline
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |toc:
-  text_transform: uppercase
+  text-transform: uppercase
 
-|line_height
+|line-height
 |<<values,Number>> +
 (default: 1.4)
 |toc:
-  line_height: 1.5
+  line-height: 1.5
 
 |indent
 |<<measurement-units,Measurement>> +
@@ -3015,127 +3164,127 @@ The keys in this category control the arrangement and style of the table of cont
 |toc:
   indent: 20
 
-|margin_top
+|margin-top
 |<<measurement-units,Measurement>> +
 (default: 0)
 |toc:
-  margin_top: 0
+  margin-top: 0
 
-3+|[#key-prefix-toc-level]*Key Prefix:* <<key-prefix-toc-level,toc_h<n> >>^[1]^
+3+|[#key-prefix-toc-level]*Key Prefix:* <<key-prefix-toc-level,toc-h<n> >>^[1]^
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |toc:
-  h3_font_color: #999999
+  h3-font-color: #999999
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |toc:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |toc:
-  font_size: 9
+  font-size: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |toc:
-  font_style: italic
+  font-style: italic
 
-|text_decoration
+|text-decoration
 |none {vbar} underline +
 (default: _inherit_)
 |toc:
-  text_decoration: none
+  text-decoration: none
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
 (default: _inherit_)
 |toc:
-  text_transform: uppercase
+  text-transform: uppercase
 
-3+|[#key-prefix-toc-title]*Key Prefix:* <<key-prefix-toc-title,toc_title>>
+3+|[#key-prefix-toc-title]*Key Prefix:* <<key-prefix-toc-title,toc-title>>
 
 |align
 |<<text-alignments,Text alignment>> +
-(default: $heading_h2_align)
+(default: $heading-h2-align)
 |toc:
   title:
     align: right
 
-|font_color
+|font-color
 |<<colors,Color>> +
-(default: $heading_h2_font_color)
+(default: $heading-h2-font-color)
 |toc:
   title:
-    font_color: #aa0000
+    font-color: #aa0000
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
-(default: $heading_h2_font_family)
+(default: $heading-h2-font-family)
 |toc:
   title:
-    font_family: Noto Serif
+    font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
-(default: $heading_h2_font_size)
+(default: $heading-h2-font-size)
 |toc:
   title:
-    font_size: 18
+    font-size: 18
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
-(default: $heading_h2_font_style)
+(default: $heading-h2-font-style)
 |toc:
   title:
-    font_style: bold_italic
+    font-style: bold_italic
 
-|text_transform
+|text-transform
 |<<text-transforms,Text transform>> +
-(default: $heading_h2_text_transform)
+(default: $heading-h2-text-transform)
 |sidebar:
   title:
-    text_transform: uppercase
+    text-transform: uppercase
 
-3+|[#key-prefix-toc-dot-leader]*Key Prefix:* <<key-prefix-toc-dot-leader,toc_dot_leader>>
+3+|[#key-prefix-toc-dot-leader]*Key Prefix:* <<key-prefix-toc-dot-leader,toc-dot-leader>>
 
 |content
 |<<quoted-string,Quoted string>> +
 (default: '. ')
 |toc:
-  dot_leader:
+  dot-leader:
     content: ". "
 
-|font_color^[2]^
+|font-color^[2]^
 |<<colors,Color>> +
 (default: _inherit_)
 |toc:
-  dot_leader:
-    font_color: #999999
+  dot-leader:
+    font-color: #999999
 
-|font_style^[2]^
+|font-style^[2]^
 |<<font-styles,Font style>> +
 (default: normal)
 |toc:
-  dot_leader:
-    font_style: bold
+  dot-leader:
+    font-style: bold
 
 |levels^[3]^
 |all {vbar} none {vbar} Integers (space-separated) +
 (default: all)
 |toc:
-  dot_leader:
+  dot-leader:
     levels: 2 3
 |===
 
 . `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
-. The dot leader inherits all font properties except `font_style` from the root `toc` category.
+. The dot leader inherits all font properties except `font-style` from the root `toc` category.
 . 0-based levels (e.g., part = 0, chapter = 1).
 Dot leaders are only shown for the specified levels.
 If value is not specified, dot leaders are shown for all levels.
@@ -3144,67 +3293,72 @@ If value is not specified, dot leaders are shown for all levels.
 === Running Content (Header & Footer)
 
 The keys in this category control the arrangement and style of running header and footer content.
+Please note that the running content will _not_ be used unless a) the periphery (header or footer) is configured and b) the height key for the periphery is assigned a value.
+
+CAUTION: If the height of the running content periphery is larger than the page margin, the running content will cover the main content.
+To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-running_content]*Key Prefix:* <<key-prefix-running_content,running_content>>
-|start_at
+3+|[#key-prefix-running-content]*Key Prefix:* <<key-prefix-running-content,running-content>>
+
+|start-at
 |title {vbar} toc {vbar} body +
 (default: body)
-|running_content:
-  start_at: toc
+|running-content:
+  start-at: toc
 
 3+|[#key-prefix-header]*Key Prefix:* <<key-prefix-header,header>>
 
-|background_color^[1]^
+|background-color^[1]^
 |<<colors,Color>> +
 (default: _not set_)
 |header:
-  background_color: #eeeeee
+  background-color: #eeeeee
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: _not set_)
 |header:
-  border_color: #dddddd
+  border-color: #dddddd
 
-|border_style
+|border-style
 |solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
 |header:
-  border_style: dashed
+  border-style: dashed
 
-|border_width
+|border-width
 |<<measurement-units,Measurement>> +
-(default: $base_border_width)
+(default: $base-border-width)
 |header:
-  border_width: 0.25
+  border-width: 0.25
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |header:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |header:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |header:
-  font_size: 9
+  font-size: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |header:
-  font_style: italic
+  font-style: italic
 
 |height^[2]^
 |<<measurement-units,Measurement>> +
@@ -3212,11 +3366,11 @@ The keys in this category control the arrangement and style of running header an
 |header:
   height: 0.75in
 
-|line_height
+|line-height
 |<<values,Number>> +
-(default: $base_line_height)
+(default: $base-line-height)
 |header:
-  line_height: 1.2
+  line-height: 1.2
 
 |padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -3224,26 +3378,38 @@ The keys in this category control the arrangement and style of running header an
 |header:
   padding: [0, 3, 0, 3]
 
-|image_vertical_align
+|image-vertical-align
 |top {vbar} middle {vbar} bottom {vbar} <<measurement-units,Measurement>> +
 (default: _not set_)
 |header:
-  image_vertical_align: 4
+  image-vertical-align: 4
+
+|sectlevels
+|Integer +
+(default: 2)
+|header:
+  sectlevels: 3
 
-|vertical_align
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: none)
+|header:
+  text-transform: uppercase
+
+|vertical-align
 |top {vbar} middle {vbar} bottom +
 (default: middle)
 |header:
-  vertical_align: center
+  vertical-align: center
 
-|<side>_columns^[4]^
+|<side>-columns^[4]^
 |Column specs triple +
 (default: _not set_)
 |header:
   recto:
     columns: <25% =50% >25%
 
-|<side>_<position>_content^[4,5]^
+|<side>-<position>-content^[4,5]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |header:
@@ -3253,53 +3419,53 @@ The keys in this category control the arrangement and style of running header an
 
 3+|[#key-prefix-footer]*Key Prefix:* <<key-prefix-footer,footer>>
 
-|background_color^[1]^
+|background-color^[1]^
 |<<colors,Color>> +
 (default: _not set_)
 |footer:
-  background_color: #eeeeee
+  background-color: #eeeeee
 
-|border_color
+|border-color
 |<<colors,Color>> +
 (default: _not set_)
 |footer:
-  border_color: #dddddd
+  border-color: #dddddd
 
-|border_style
+|border-style
 |solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
 |footer:
-  border_style: dashed
+  border-style: dashed
 
-|border_width
+|border-width
 |<<measurement-units,Measurement>> +
-(default: $base_border_width)
+(default: $base-border-width)
 |footer:
-  border_width: 0.25
+  border-width: 0.25
 
-|font_color
+|font-color
 |<<colors,Color>> +
 (default: _inherit_)
 |footer:
-  font_color: #333333
+  font-color: #333333
 
-|font_family
+|font-family
 |<<fonts,Font family name>> +
 (default: _inherit_)
 |footer:
-  font_family: Noto Serif
+  font-family: Noto Serif
 
-|font_size
+|font-size
 |<<values,Number>> +
 (default: _inherit_)
 |footer:
-  font_size: 9
+  font-size: 9
 
-|font_style
+|font-style
 |<<font-styles,Font style>> +
 (default: _inherit_)
 |footer:
-  font_style: italic
+  font-style: italic
 
 |height^[2]^
 |<<measurement-units,Measurement>> +
@@ -3307,11 +3473,11 @@ The keys in this category control the arrangement and style of running header an
 |footer:
   height: 0.75in
 
-|line_height
+|line-height
 |<<values,Number>> +
-(default: $base_line_height)
+(default: $base-line-height)
 |footer:
-  line_height: 1.2
+  line-height: 1.2
 
 |padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
@@ -3319,26 +3485,38 @@ The keys in this category control the arrangement and style of running header an
 |footer:
   padding: [0, 3, 0, 3]
 
-|image_vertical_align
+|image-vertical-align
 |top {vbar} middle {vbar} bottom {vbar} <<measurement-units,Measurement>> +
 (default: _not set_)
 |footer:
-  image_vertical_align: 4
+  image-vertical-align: 4
 
-|vertical_align
+|sectlevels
+|Integer +
+(default: 2)
+|footer:
+  sectlevels: 3
+
+|text-transform
+|<<text-transforms,Text transform>> +
+(default: none)
+|footer:
+  text-transform: uppercase
+
+|vertical-align
 |top {vbar} middle {vbar} bottom +
 (default: middle)
 |footer:
-  vertical_align: top
+  vertical-align: top
 
-|<side>_columns^[4]^
+|<side>-columns^[4]^
 |Column specs triple +
 (default: _not set_)
 |footer:
   verso:
     columns: <50% =0% <50%
 
-|<side>_<position>_content^[4,5]^
+|<side>-<position>-content^[4,5]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |footer:
@@ -3347,21 +3525,21 @@ The keys in this category control the arrangement and style of running header an
       content: '\{page-number}'
 |===
 . The background color spans the width of the page, as does the border when a background color is specified.
-. If the height is not set, the running content at this periphery is disabled.
+. *If the height is not set, the running content at this periphery is disabled.*
 . If the side padding is negative, the content will bleed into the margin of the page.
 . `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
 Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
 . `<position>` can be `left`, `center` or `right`.
 
-IMPORTANT: You must define a height for the running header or footer, respectively, or it will not be shown.
+IMPORTANT: If you don't specify a height for either the header or footer key, it effectively disables the content at that periphery.
 
-If you define running header and footer content in your theme, you can still disable this content per document by setting the `noheader` and `nofooter` attributes in the AsciiDoc document header, respectively.
+If you define running header and footer content in your theme (including the height), you can still disable this content per document by setting the `noheader` and `nofooter` attributes in the AsciiDoc document header, respectively.
 
 If content is not specified for the running footer, the page number (i.e., `\{page-number}`) is shown on the left on verso pages and the right on recto pages.
-You can disable this behavior by defining the attribute `nofooter` in the AsciiDoc document header or by defining the key `footer_<side>_content: none` in the theme.
+You can disable this behavior by defining the attribute `nofooter` in the AsciiDoc document header or by defining the key `footer-<side>-content: none` in the theme.
 
-TIP: Although not listed in the table above, you can control the font properties used for running content for each column position on each page side (e.g., `footer_<side>_<position>_font_color`).
-For example, you can set the font color used for the right-hand column on recto pages by setting `footer_recto_right_font_color: 6CC644`.
+TIP: Although not listed in the table above, you can control the font settings (font-family, font-size, font-color, font-style, text-transform) that get applied to the running content in each column position for each page side (e.g., `footer-<side>-<position>-font-color`).
+For example, you can set the font color used for the right-hand column on recto pages by setting `footer-recto-right-font-color: 6CC644`.
 
 ==== Attribute References
 
@@ -3385,16 +3563,16 @@ Here's an example that shows how attributes and replacements can be used in the
 ----
 header:
   height: 0.75in
-  line_height: 1
+  line-height: 1
   recto:
     center:
       content: '(C) ACME -- v{revnumber}, {docdate}'
   verso:
     center:
-      content: $header_recto_center_content
+      content: $header-recto-center-content
 footer:
   height: 0.75in
-  line_height: 1
+  line-height: 1
   recto:
     right:
       content: '{section-or-chapter-title} | *{page-number}*'
@@ -3411,7 +3589,7 @@ To force a hard line break in the output, add `{sp}+` to the end of the line in
 ----
 footer:
   height: 0.75in
-  line_height: 1.2
+  line-height: 1.2
   recto:
     right:
       content: |
@@ -3440,20 +3618,20 @@ Here's an example of how to use an image in the running header (which also appli
 ----
 header:
   height: 0.75in
-  image_vertical_align: 2 {conum-guard-yaml} <1>
+  image-vertical-align: 2 {conum-guard-yaml} <1>
   recto:
     center:
       content: image:footer-logo.png[width=80]
   verso:
     center:
-      content: $header_recto_center_content
+      content: $header-recto-center-content
 ----
-<1> You can use the `footer_vertical_align` attribute to slighly nudge the image up or down.
+<1> You can use the `footer-vertical-align` attribute to slighly nudge the image up or down.
 
 CAUTION: By default, the image must fit in the allotted space for the running header or footer.
 Otherwise, you will run into layout issues.
 Adjust the width attribute accordingly using the `pdfwidth` attribute.
-Alternatively, you can set the `fit` attribute to `scale-down` (e.g., `fit=scale-down`) to reduce the image size to fit in the available space or `contain` (e.g., `fit=contain`) to resize the image to the maximum size that will fit.
+Alternatively, you can set the `fit` attribute to `scale-down` (e.g., `fit=scale-down`) to reduce the image size to fit in the available space or `contain` (i.e., `fit=contain`) to scale the image (up or down) to fit the available space.
 
 == Applying Your Theme
 
@@ -3462,14 +3640,15 @@ This is done using AsciiDoc attributes.
 
 There are three AsciiDoc attributes that tell Asciidoctor PDF how to locate and apply your theme.
 
-pdf-stylesdir:: The directory where the theme file is located.
+pdf-theme (or pdf-style):: The name of the YAML theme file to load.
+If the name ends with `.yml`, it's assumed to be the complete name of a file and is resolved relative to `pdf-themesdir`, if specified, otherwise the current directory.
+Otherwise, `-theme.yml` is appended to the name to make the file name (i.e., `<name>-theme.yml`) and is resolved relative to `pdf-themesdir`, if specified, otherwise the built-in themes dir.
+
+pdf-themesdir (or pdf-stylesdir):: The directory where the theme file is located.
 _Specifying an absolute path is recommended._
 +
 If you use images in your theme, image paths are resolved relative to this directory.
-
-pdf-style:: The name of the YAML theme file to load.
-If the name ends with `.yml`, it's assumed to be the complete name of a file.
-Otherwise, `-theme.yml` is appended to the name to make the file name (i.e., `<name>-theme.yml`).
+If `pdf-theme` ends with `.yml`, and `pdf-themesdir` is not specified, then `pdf-themesdir` defaults to the directory of the path specified by `pdf-theme`.
 
 pdf-fontsdir:: The directory where the fonts used by your theme, if any, are located.
 _Specifying an absolute path is recommended._
@@ -3490,15 +3669,15 @@ resources/
 
 Here's how you'd load your theme when calling Asciidoctor PDF:
 
- $ asciidoctor-pdf -a pdf-stylesdir=resources/themes -a pdf-style=basic -a pdf-fontsdir=resources/fonts
+ $ asciidoctor-pdf -a pdf-themesdir=resources/themes -a pdf-theme=basic -a pdf-fontsdir=resources/fonts
 
 If all goes well, Asciidoctor PDF should run without an error or warning.
 
 NOTE: You only need to specify the `pdf-fontsdir` if you are using custom fonts in your theme.
 
-You can skip setting the `pdf-stylesdir` attribute and just pass the absolute path of your theme file to the `pdf-style` attribute.
+You can skip setting the `pdf-themesdir` attribute and just pass the absolute path of your theme file to the `pdf-theme` attribute.
 
- $ asciidoctor-pdf -a pdf-style=resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts
+ $ asciidoctor-pdf -a pdf-theme=resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts
 
 However, in this case, image paths in your theme won't be resolved properly.
 
@@ -3506,7 +3685,7 @@ Paths are resolved relative to the current directory.
 However, in the future, this may change so that paths are resolved relative to the base directory (typically the document's directory).
 Therefore, it's recommend that you specify absolute paths for now to future-proof your configuration.
 
-  $ asciidoctor-pdf -a pdf-stylesdir=/path/to/resources/themes -a pdf-style=basic -a pdf-fontsdir=/path/to/resources/fonts
+ $ asciidoctor-pdf -a pdf-themesdir=/path/to/resources/themes -a pdf-theme=basic -a pdf-fontsdir=/path/to/resources/fonts
 
 As usual, you can also use build tools like Maven and Gradle to build a themed PDF.
 The only thing you need to add to an existing build is the attributes mentioned above.
@@ -3540,10 +3719,18 @@ These settings override equivalent keys defined in the theme file, where applica
 |screen {vbar} print {vbar} prepress
 |:media: prepress
 
+|outlinelevels
+|number (default: same as _toclevels_)
+|:outlinelevels: 2
+
 |page-background-image^[4]^
 |path^[2]^ {vbar} image macro^[3]^
 |:page-background-image: image:bg.jpg[]
 
+|page-background-image-(recto{vbar}verso)^[4]^
+|path^[2]^ {vbar} image macro^[3]^
+|:page-background-image-recto: image:bg-recto.jpg[]
+
 |pagenums^[5]^
 |flag (default: _set_)
 |:pagenums:
@@ -3564,13 +3751,17 @@ These settings override equivalent keys defined in the theme file, where applica
 |virtual {vbar} virtual-inverted {vbar} physical {vbar} physical-inverted
 |:pdf-folio-placement: physical
 
+|pdf-version
+|1.3 {vbar} 1.4 {vbar} 1.5 {vbar} 1.6 {vbar} 1.7 (default: 1.4)
+|:pdf-version: 1.7
+
 |pdfmark^[6]^
 |flag (default: _not set_)
 |:pdfmark:
 
-|text-alignment^[7]^
+|text-align^[7]^
 |<<text-alignments,Text alignment>>
-|:text-alignment: left
+|:text-align: left
 
 |title-logo-image
 |path^[2]^ {vbar} image macro^[3]^
@@ -3589,17 +3780,16 @@ These settings override equivalent keys defined in the theme file, where applica
 . The path is resolved relative to base_dir.
 . The target of the image macro is resolved relative to `imagesdir`.
 If the image macro syntax is not used, the value is resolved relative to the base directory, which defaults to the document directory.
-. Page background images are automatically scaled to fit within the bounds of the page.
-+
-NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
-This limitation is due to a bug in Prawn 1.3.1.
-The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
-For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
+. By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
+The size of the background can be controlled using any of the sizing attributes on the image macro (i.e., fit, pdfwidth, scaledwidth, or width).
+If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background is specified, it will be used only for that side.
+If a background image isn't specified for a side, the converter will use the default page background image (`page-background-image`), if specified.
+To disable the background for a side, use the value `none`.
 . Controls whether the `page-number` attribute is accessible to the running header and footer content specified in the theme file.
 Use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively, from the document.
 . Enables generation of the http://milan.kupcevic.net/ghostscript-ps-pdf/#marks[pdfmark] file, which contains metadata that is fed to Ghostscript when optimizing the PDF file.
-. _(Experimental)_ The `text-alignment` document attribute is intended as a simple way to toggle text justification.
-The value of this attribute overrides the `base_align` key set by the theme.
+. _(Experimental)_ The `text-align` document attribute is intended as a simple way to toggle text justification.
+The value of this attribute overrides the `base-align` key set by the theme.
 For more fine-grained control, you should customize using the theme.
 . Force a title page to be added even when the doctype is not book.
 
@@ -3615,7 +3805,7 @@ The following sections describe the behaviors that this setting activates.
 
 === Double-Sided Page Margins
 
-The page margins for the recto (right-hand, odd-numbered) and verso (left-hand, even-numbered) pages are automatically calculated by replacing the side page margins with the values of the `page_margin_inner` and `page_margin_outer` keys.
+The page margins for the recto (right-hand, odd-numbered) and verso (left-hand, even-numbered) pages are automatically calculated by replacing the side page margins with the values of the `page-margin-inner` and `page-margin-outer` keys.
 
 For example, let's assume you've defined the following settings in your theme:
 
@@ -3623,8 +3813,8 @@ For example, let's assume you've defined the following settings in your theme:
 ----
 page:
   margin: [0.5in, 0.67in, 0.67in, 0.67in]
-  margin_inner: 0.75in
-  margin_outer: 0.59in
+  margin-inner: 0.75in
+  margin-outer: 0.59in
 ----
 
 The page margins for the recto and verso pages will be resolved as follows: