asciidoctor-pdf 1.5.0.alpha.11 → 1.5.0.alpha.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d57d63736925f3f95abbe68750ee04c0011da449
-  data.tar.gz: 67c4ec4db9b252a03ae6baa1c3e5bebf3deb57a7
+  metadata.gz: e5b988f6863043a9a22bf55cdbbef3a12a9c9a16
+  data.tar.gz: a623fe7f63d9311404fadca17ff1f17f97b13add
 SHA512:
-  metadata.gz: 06d8e5edb049cf5cd1622f04b6f91eac6b366a06dd58647dc086d33f26ddb9bc15b5b00956c8a7df06d00ead309a418fdb436795e1eb1a73353b753fdb099fda
-  data.tar.gz: b059d077c26efc23b45d0cbe28b0249ca4e7738021d58028a9a19e8ee7255da7357d30c95cd5878c4c93502dbf6a5617484e3eda6f740a39d78643ca20f52cf5
+  metadata.gz: 1311807ce5e4b061faddbb7dd2cce3bc8f563c4a004849f082de2a8e625e90b1d097524e26e1bc97a21b3f363f5de262c649f6888c009e2cd6a6234135d95b21
+  data.tar.gz: b296d8fbc882739a27b033032c0be761fb0cc9ad0b03a245865e2869be49d8608d9f6b64fc43af061c369c99b217c6846a5da66a14a8dafb3751942e8a1eef66

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'prawn', '1.3.0' if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0.0')
+
+# Look in asciidoctor-pdf.gemspec for runtime and development dependencies
+gemspec
+
+group :examples do
+  gem 'rouge', '2.0.5'
+end

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.11, 2016-01-05
+v1.5.0.alpha.12, 2016-08-05
 // Settings:
 :compat-mode!:
 :experimental:
@@ -94,6 +94,10 @@ See <<WORKLOG.adoc#,WORKLOG>>.
 
 All that's needed is Ruby (1.9.3 or above; 2.2.x recommended) and a few Ruby gems, which we explain how to install in the next section.
 
+To check if you have Ruby available, use the `ruby` command to query the version installed:
+
+ $ ruby --version
+
 [WARNING]
 ====
 Prawn 2.0.0 and above requires Ruby >= 2.0.0 at installation (though it still works with Ruby 1.9.3 once you get beyond installation).
@@ -104,9 +108,18 @@ If you need to use Asciidoctor PDF with Ruby 1.9.3, you must first install Prawn
 You can then proceed with installation of Asciidoctor PDF.
 ====
 
-To check if you have Ruby available, use the `ruby` command to query the version installed:
+=== System encoding
 
- $ ruby --version
+Asciidoctor assumes you're using UTF-8 encoding.
+To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.
+
+If you're using a non-English Windows environment, the default encoding of your system may not be UTF-8.
+As a result, you may get an `Encoding::UndefinedConversionError` or other encoding issues when invoking Asciidoctor.
+To solve these problems, we recommend at least changing the active code page in your console to UTF-8.
+
+ chcp 65001
+
+Once you make this change, all your Unicode headaches will be behind you.
 
 == Getting started
 
@@ -165,7 +178,7 @@ It's time to convert the AsciiDoc document directly to PDF.
 
 === Convert AsciiDoc to PDF
 
-IMPORTANT: You'll need the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`.
+IMPORTANT: You'll need the `rouge` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `rouge`.
 
 Converting to PDF is a simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
 
@@ -194,7 +207,7 @@ The layout and styling of the PDF is driven by a YAML configuration file.
 To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>.
 You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.
 
-== Font-based Icons
+== Font-based icons
 
 You can use icons in your PDF document using any of the following icon sets:
 
@@ -246,6 +259,54 @@ You can enable use of fonts during PDF generation (instead of in the document he
 Icon-based fonts are handled by the `prawn-icon` gem.
 To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.
 
+== Image scaling
+
+Since PDF is a fixed-width canvas, you almost always need to specify an image width to get the image to fit properly on the page.
+There are four ways to specify the width of the image, listed here in order of precedence:
+
+[cols="1s,3d"]
+|===
+|Attribute{nbsp}Name | Description
+
+|pdfwidth
+|The display width of the image as an absolute size (e.g., 2in), percentage of the content width (e.g., 75%), or percentage of the page width (e.g., 100vw).
+_Intended to be used for the PDF converter only._
+
+|scaledwidth
+|The display width of the image as a percentage of the content width (e.g., 75%).
+_Intended to be used for print output such as PDF._
+
+|width
+|The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
+If the width exceeds the content width, the image is scaled down to the content width.
+
+|_unspecified_
+|If you don't specify one of the width attributes, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt) unless the width exceeds the content width, in which case the image is scaled down to the content width.
+|===
+
+The sizing is always controlled by the width (explicit or intrinsic) and the size of the image is scaled proporationally.
+The height of the image is ignored by the PDF converter, with one exception.
+If the height of the image exceeds the height of the page, the image is scaled down to fit on a single page.
+
+=== pdfwidth attribute
+
+The pdfwidth attribute is the recommended way to set the image size for the PDF output.
+This attribute is provided for two reasons.
+First, the fixed-width canvas often calls for a width that is distinct from other output formats, such as HTML.
+Second, this attribute allows the width to be expressed using a variety of units.
+
+The pdfwidth attribute supports the following units:
+
+* pt (default)
+* in
+* mm
+* cm
+* px
+* % (percentage of content width)
+* vw (percentage of page width)
+
+In all cases, the width is converted to pt.
+
 == Optional scripts
 
 {project-name} also provides a shell script that invokes GhostScript (`gs`) to optimize and compress the generated PDF with minimal impact on quality.

data/asciidoctor-pdf.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('lib/asciidoctor-pdf/version', File.dirname(__FILE__))
+require 'open3' unless defined? Open3
+
+Gem::Specification.new do |s|
+  s.name = 'asciidoctor-pdf'
+  s.version = Asciidoctor::Pdf::VERSION
+
+  s.summary = 'Converts AsciiDoc documents to PDF using Prawn'
+  s.description = <<-EOS
+An extension for Asciidoctor that converts AsciiDoc documents to PDF using the Prawn PDF library.
+  EOS
+
+  s.authors = ['Dan Allen', 'Sarah White']
+  s.email = 'dan@opendevise.io'
+  s.homepage = 'https://github.com/asciidoctor/asciidoctor-pdf'
+  s.license = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  files = begin
+    (result = Open3.popen3('git ls-files -z') {|_, out| out.read }.split %(\0)).empty? ? Dir['**/*'] : result
+  rescue
+    Dir['**/*']
+  end
+  s.files = files.grep /^(?:(?:data|docs|lib)\/.+|Gemfile|Rakefile|(?:LICENSE|NOTICE|README)\.adoc|#{s.name}\.gemspec)$/
+  # FIXME optimize-pdf is currently a shell script, so listing it here won't work
+  #s.executables = ['asciidoctor-pdf', 'optimize-pdf']
+  s.executables = ['asciidoctor-pdf']
+  s.test_files = files.grep /^(?:test|spec|feature)\/.*$/
+
+  s.require_paths = ['lib']
+
+  s.has_rdoc = true
+  s.rdoc_options = ['--charset=UTF-8', '--title="Asciidoctor PDF"', '--main=README.adoc', '-ri']
+  s.extra_rdoc_files = ['README.adoc', 'LICENSE.adoc', 'NOTICE.adoc']
+
+  s.add_development_dependency 'rake'
+  #s.add_development_dependency 'rdoc', '~> 4.1.0'
+
+  s.add_runtime_dependency 'asciidoctor', '>= 1.5.0'
+  # Prawn 2.x requires Ruby 2.x, so cast a wider net
+  s.add_runtime_dependency 'prawn', '>= 1.3.0', '< 3.0.0'
+  s.add_runtime_dependency 'prawn-table', '0.2.2'
+  s.add_runtime_dependency 'prawn-templates', '0.0.3'
+  s.add_runtime_dependency 'prawn-svg', '0.25.1'
+  s.add_runtime_dependency 'prawn-icon', '1.1.0'
+  s.add_runtime_dependency 'safe_yaml', '~> 1.0.4'
+  s.add_runtime_dependency 'thread_safe', '~> 0.3.5'
+  # For our usage, treetop 1.6.2 is slower than 1.5.3
+  s.add_runtime_dependency 'treetop', '1.5.3'
+end

data/data/themes/default-theme.yml

@@ -70,14 +70,15 @@ link:
 literal:
   font_color: b12146
   font_family: M+ 1mn
+menu_caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
 heading:
   #font_color: 181818
   font_color: $base_font_color
   font_family: $base_font_family
   font_style: bold
-  # h1 is used for part titles
+  # h1 is used for part titles (book doctype only)
   h1_font_size: floor($base_font_size * 2.6)
-  # h2 is used for chapter titles
+  # h2 is used for chapter titles (book doctype only)
   h2_font_size: floor($base_font_size * 2.15)
   h3_font_size: round($base_font_size * 1.7)
   h4_font_size: $base_font_size_large

data/docs/theming-guide.adoc

@@ -1,26 +1,42 @@
 = Asciidoctor PDF Theming Guide
-Dan Allen <https://github.com/mojavelinux>
-:toc: macro
-:icons: font
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+// Settings:
 :idprefix:
 :idseparator: -
+:toc: preamble
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
 :window: _blank
+// Aliases:
+:conum-guard-yaml: #
+ifndef::icons[:conum-guard-yaml: # #]
 
 ////
 Topics remaining to document:
-* document which attributes can be set in document (pdf-page-size, front-cover-image, back-cover-image, etc)
+* document which attributes can be set in document (pdf-page-size, front-cover-image, back-cover-image, etc) (issue #428)
 * line height and line height length (and what that all means)
 * title page layout / title page images (logo & background)
 * document that unicode escape sequences can be used inside double-quoted strings
 ////
 
-The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file that Asciidoctor PDF generates from AsciiDoc.
-The theme is driven by a YAML-based configuration file.
-This document explains how the theming system works, how to define a custom theme and how to enable the theme when running Asciidoctor PDF.
+[.lead]
+The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file Asciidoctor PDF generates from AsciiDoc.
+This document describes how the theming system works, how to define a custom theme in YAML and how to activate the theme when running Asciidoctor PDF.
+
+IMPORTANT: If you're using a custom theme, you're expected to override some of keys described in the sections below, in particular fonts.
+If you don't define your own fonts, the built-in PDF fonts will be used.
 
 toc::[]
 
-== Language overview
+== 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.
@@ -63,13 +79,13 @@ base:
   font_size: 12
   line_height_length: 17
   line_height: $base_line_height_length / $base_font_size
-vertical_rhythm: $base_line_height_length
+vertical_spacing: $base_line_height_length
 heading:
   font_color: #262626
   font_size: 17
   font_style: bold
   line_height: 1.2
-  margin_bottom: $vertical_rhythm
+  margin_bottom: $vertical_spacing
 link:
   font_color: #002FA7
 outline_list:
@@ -132,6 +148,10 @@ The value of a key may be one of the following types:
   - Alignment (left, center, right, justify)
   - Color as hex string (e.g., #ffffff)
   - Image path
+* Null (clears any previously assigned value)
+  - _empty_ (i.e., no value specified)
+  - null
+  - ~
 * Number (integer or float) with optional units (default unit is points)
 * Array
   - Color as RGB array (e.g., [51, 51, 51])
@@ -157,11 +177,12 @@ The following keys are inherited:
 * font_style
 * line_height (currently some exceptions)
 * text_transform (only for headings)
-* margin_bottom (falls back to $vertical_rhythm)
+* margin_bottom (falls back to $vertical_spacing)
 
 .Heading Inheritance
 ****
-Headings are special in that they inherit starting from a specific heading level (e.g., `heading_font_size_h2`) to the heading category (e.g., `heading_font_size`) and then directly to the base value (e.g., `base_font_size`), skipping any enclosing context.
+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
@@ -207,7 +228,7 @@ base:
 
 We'll cover more about math expressions later.
 
-==== Custom variables
+==== Custom Variables
 
 You can define arbitrary key names to make custom variables.
 This is one way to group reusable values at the top of your theme file.
@@ -215,12 +236,12 @@ If you are going to do this, it's recommended that you organize the keys under a
 
 For instance, here's how you can define your brand colors:
 
-[source,yaml]
+[source,yaml,subs=attributes+]
 ----
 brand:
-  primary: #E0162B # <1>
-  secondary: '#FFFFFF' # <2>
-  alert: '0052A5' # <3>
+  primary: #E0162B {conum-guard-yaml} <1>
+  secondary: '#FFFFFF' {conum-guard-yaml} <2>
+  alert: '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.
@@ -236,9 +257,11 @@ base:
   font_color: $brand_primary
 ----
 
-=== Math expressions & functions
+=== Math Expressions & Functions
 
 The theme language supports basic math operations to support calculated values.
+Like programming languages, multiple and divide take precedence over add and subtract.
+
 The following table lists the supported operations and the corresponding operator for each.
 
 [%header%autowidth]
@@ -258,9 +281,8 @@ The following table lists the supported operations and the corresponding operato
 |-
 |===
 
-NOTE: Like programming languages, multiple and divide take precedence over add and subtract.
+IMPORTANT: The operator must always be surrounded by a space on either side (e.g., 2 + 2 and not 2+2).
 
-The operator must always be surrounded by a space on either side.
 Here's an example of a math expression with fixed values.
 
 [source,yaml]
@@ -299,7 +321,7 @@ base:
   font_size_large: ceil($base_font_size * 1.25)
 ----
 
-=== Measurement units
+=== Measurement Units
 
 Several of the keys require a value in points (pt), the unit of measure for the PDF canvas.
 A point is defined as 1/72 of an inch.
@@ -477,7 +499,12 @@ title_page:
 You can select from <<built-in-afm-fonts,built-in PDF fonts>>, <<bundled-fonts,fonts bundled with Asciidoctor PDF>> or <<custom-fonts,custom fonts>> loaded from TrueType font (TTF) files.
 If you want to use custom fonts, you must first declare them in your theme file.
 
-=== Built-in (AFM) fonts
+IMPORTANT: Asciidoctor has no challenge working with Unicode.
+In fact, it prefers Unicode and considers the whole range.
+However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters.
+There's nothing Asciidoctor can do to convince PDF to work without the right fonts in play.
+
+=== Built-In (AFM) Fonts
 
 The names of the built-in fonts (for general-purpose text) are as follows:
 
@@ -512,7 +539,7 @@ For anything outside of that, PDF is BYOF (Bring Your Own Font).
 Even though the built-in fonts require the content to be encoded in WINANSI, _you still type your AsciiDoc document in UTF-8_.
 Asciidoctor PDF encodes the content into WINANSI when building the PDF.
 
-.WINANSI encoding behavior
+.WINANSI Encoding Behavior
 ****
 If you're using Prawn 1.3.0 with one of the built-in fonts, any characters in your AsciiDoc document that cannot be encoded to WINANSI will be replaced with an underscore glyph (`_`).
 If you're using Prawn 2.0.0 or above with one of the built-in fonts, if your AsciiDoc document contains a character that cannot be encoded to WINANSI, a warning will be issued and conversion will halt.
@@ -520,7 +547,7 @@ If you're using Prawn 2.0.0 or above with one of the built-in fonts, if your Asc
 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].
 ****
 
-=== Bundled fonts
+=== Bundled Fonts
 
 Asciidoctor PDF bundles several fonts that are used in the default theme.
 You can also use these fonts in your custom theme.
@@ -543,7 +570,7 @@ Useful as a fallback font.
 CAUTION: At the time of this writing, you cannot use the bundled fonts if you define your own custom fonts.
 This limitation may be lifted in the future.
 
-=== Custom fonts
+=== Custom Fonts
 
 The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font.
 Custom fonts can enhance the look of your PDF theme substantially.
@@ -621,7 +648,7 @@ TIP: Text in SVGs will use the font catalog from your theme.
 We recommend that you match the font key to the name of the font seen by the operating system.
 This will allow you to use the same font names (aka families) in both your graphics program and Asciidoctor PDF.
 
-=== Fallback fonts
+=== Fallback Fonts
 
 If one of your fonts is missing a character that is used in a document, such as special symbols, you can tell Asciidoctor PDF to retrieve the character from a fallback font.
 You only need to specify one fallback font...typically one that has a full set of symbols.
@@ -677,321 +704,596 @@ It's best to select fonts that have all the characters you need.
 
 == Keys
 
-TBW
+This section lists all the keys that are available when creating a custom theme.
+The converter uses the values of these keys to control how most elements are arranged and styled in the PDF.
+
+NOTE: When creating a theme, all keys are optional.
+You only have to assign values to keys you want to customize.
+Any required keys are assigned by the base theme.
+
+The keys in this section are organized by category.
+Each category represents a common prefix under which the keys are typically nested.
+The default values are those assigned by the base theme (not the default theme).
+
+TIP: Keys can be partioned and nested wherever an underscore (`_`) appears in the name.
+This nested structure is flatted when the theme is loaded.
 
 === Page
 
-[cols="3,3,5m"]
+The keys in this category control the size, margins and background of each page (i.e., canvas).
+
+NOTE: The background of the title page can be styled independently.
+See <<Title Page>> for details.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|page_background_color^[1]^
-|<<colors,color>>
-|background_color: #ffffff
+3+|*Key Prefix:* page
 
-|page_background_image^[1]^
-|path (absolute or relative to pdf-stylesdir)
-|+background_image: image:watermark.png[]+
-
-|page_layout
-|portrait, landscape +
-(default: portrait)
-|layout: portrait
+|background_color^[1]^
+|<<colors,Color>> +
+(default: #ffffff)
+|page:
+  background_color: #fefefe
 
-|page_margin
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|margin: [0.5in, 0.67in, 0.67in, 0.67in]
+|background_image^[1]^
+|Inline image macro^[2]^ +
+(default: none)
+|page:
+  background_image: +image:page-bg.png[]+
 
-|page_size
-|named size, <<measurement-units,measurement array [width, height]>>
-|size: Letter
+|layout
+|portrait {vbar} landscape +
+(default: portrait)
+|page:
+  layout: landscape
+
+|margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: 36)
+|page:
+  margin: [0.5in, 0.67in, 1in, 0.67in]
+
+|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
 |===
 
-^[1]^ Page background colors and images do not currently work when using AsciidoctorJ PDF.
+. 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.
 
 === Base
 
-[cols="3,3,5m"]
+The keys in this category provide generic theme settings and are often referenced throughout the theme file as variables.
+It's common to define additional keys in this category (e.g., `base_border_radius`) that serve as custom variables to help keep your theme DRY.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|base_font_color
-|<<colors,color>>
-|font_color: #333333
-
-|base_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
-
-|base_font_size
-|<<values,number>>
-|font_size: 10.5
-
-|base_line_height_length^[1]^
-|<<values,number>>
-|line_height_length: 12
-
-|base_line_height^[1]^
-|<<values,number>>
-|line_height: 1.14
-
-|base_font_size_large
-|<<values,number>>
-|font_size_large: 13
-
-|base_font_size_small
-|<<values,number>>
-|font_size_small: 9
-
-|base_font_size_min
-|<<values,number>>
-|font_size_small: 6
+3+|*Key Prefix:* base
 
-|base_font_style
-|normal, italic, bold, bold_italic
-|font_style: normal
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: left)
+|base:
+  align: justify
 
-|base_align
-|left, center, right, justify
-|align: justify
-
-|base_border_radius
-|<<values,number>>
-|border_radius: 4
-
-|base_border_width
-|<<values,number>>
-|border_width: 0.5
+|font_color
+|<<colors,Color>> +
+(default: #000000)
+|base:
+  font_color: #333333
 
-|base_border_color
-|<<colors,color>>
-|border_color: #eeeeee
+|font_family
+|<<fonts,Font family name>> +
+(default: Helvetica)
+|base:
+  font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: 12)
+|base:
+  font_size: 10.5
+
+// font_size_large and font_size_small aren't official keys
+//|font_size_large
+//|<<values,Number>>
+//|base:
+//  font_size_large: 13
+//
+//|font_size_small
+//|<<values,Number>>
+//|base:
+//  font_size_small: 9
+
+|font_size_min
+|<<values,Number>> +
+(default: 9)
+|base:
+  font_size_min: 6
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: normal)
+|base:
+  font_style: normal
+
+|line_height_length^[1]^
+|<<values,Number>> +
+(default: 13.8)
+|base:
+  line_height_length: 12
+
+|line_height^[1]^
+|<<values,Number>> +
+(default: 1.15)
+|base:
+  line_height: >
+    $base_line_height_length /
+    $base_font_size
+
+// border_radius is not an official key
+//|border_radius
+//|<<values,Number>>
+//|base:
+//  border_radius: 4
+
+|border_width
+|<<values,Number>> +
+(default: 0.5)
+|base:
+  border_width: 0.5
+
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|base:
+  border_color: #eeeeee
 |===
 
-^[1]^ You should set either `line_height` or `line_height_length` and derive the value of the other using a calculation since these are correlated values.
-For instance, if you set `line_height_length`, then use `line_height: $base_line_height_length / $base_font_size` to define the 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`.
 
-=== Vertical and horizontal rhythm
+=== Vertical Spacing
 
-[cols="3,3,5m"]
+The keys in this category control the general spacing between elements where a more specific setting is not designated.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|vertical_rhythm
-|<<values,number>>
-|vertical_rhythm: 12
-
-|horizontal_rhythm
-|<<values,number>>
-|horizontal_rhythm: 12
+|vertical_spacing
+|<<values,Number>> +
+(default: 12)
+|vertical_spacing: 10
 |===
 
-NOTE: Vertical and horizontal rhythm are used for vertical and horizontal spacing, respectively, when there a specific theme key is not defined for a certain purpose.
-These keys predated the CSS-style theme system and are planned to be phased out.
-
 === Link
 
-[cols="3,3,5m"]
+The keys in this category are used to style hyperlink text.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|link_font_color
-|<<colors,color>>
-|font_color: #428bca
-
-|link_font_family
-|<<fonts,font family name>>
-|font_family: Roboto
-
-|link_font_size
-|<<values,number>>
-|font_size: 9
-
-|link_font_style
-|normal, italic, bold, bold_italic
-|font_style: normal
+3+|*Key Prefix:* link
+
+|font_color
+|<<colors,Color>> +
+(default: #0000ee)
+|link:
+  font_color: #428bca
+
+// font_family, font_size and font_style not yet implemented
+//|font_family
+//|<<fonts,Font family name>>
+//|link:
+//  font_family: Roboto
+//
+//|font_size
+//|<<values,Number>>
+//|link:
+//  font_size: 9
+//
+//|font_style
+//|normal {vbar} italic {vbar} bold {vbar} bold_italic
+//|link:
+//  font_style: normal
 |===
 
-=== Literal inline
+=== Literal (Inline)
 
-The literal key is used for inline monospaced text in prose and table cells.
+The keys in this category are used for inline monospaced text in prose and table cells.
 
-[cols="3,3,5m"]
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|literal_font_color
-|<<colors,color>>
-|font_color: #b12146
+3+|*Key Prefix:* literal
 
-|literal_font_family
-|<<fonts,font family name>>
-|font_family: M+ 1mn
+|font_color
+|<<colors,Color>>
+|literal:
+  font_color: #b12146
 
-|literal_font_size
-|<<values,number>>
-|font_size: 12
+|font_family
+|<<fonts,Font family name>> +
+(default: Courier)
+|literal:
+  font_family: M+ 1mn
 
-|literal_font_style
-|normal, italic, bold, bold_italic
-|font_style: bold
+|font_size
+|<<values,Number>>
+|literal:
+  font_size: 12
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|literal:
+  font_style: bold
 |===
 
 === Heading
 
-[cols="3,3,5m"]
+The keys in this category control the style of most headings, including part titles, chapter titles, sections titles, the table of contents title and discrete headings.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|heading_font_color
-|<<colors,color>>
-|font_color: #333333
-
-|heading_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
-
-|heading_font_size
-|<<values,number>>
-|font_size: 9
-
-|heading_font_style
-|normal, italic, bold, bold_italic
-|font_style: bold
+3+|*Key Prefix:* heading
+
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: left)
+|heading:
+  align: center
+
+|font_color
+|<<colors,Color>> +
+(default: $base_font_color)
+|heading:
+  font_color: #222222
+
+|font_family
+|<<fonts,Font family name>> +
+(default: $base_font_family)
+|heading:
+  font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: $base_font_size)
+|heading:
+  font_size: 18
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: bold)
+|heading:
+  font_style: bold
 
-|heading_h<n>_font_color^[1]^
-|<<colors,color>>
-|h2_font_color: [0, 99%, 100%, 0]
+|line_height
+|<<values,Number>> +
+(default: 1.15)
+|heading:
+  line_height: 1.2
 
-|heading_h<n>_font_family^[1]^
-|<<fonts,font family name>>
-|h4_font_family: Roboto
+|margin_top
+|<<measurement-units,Measurement>> +
+(default: 4)
+|heading:
+  margin_top: $vertical_spacing * 0.2
+
+|margin_bottom
+|<<measurement-units,Measurement>> +
+(default: 12)
+|heading:
+  margin_bottom: 9.6
+
+|text_transform
+|none {vbar} uppercase {vbar} lowercase +
+(default: none)
+|heading:
+  text_transform: uppercase
+
+3+|*Key Prefix:* heading_h<n>^[1]^
+
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: $heading_align)
+|heading:
+  h2_align: center
+
+|font_color
+|<<colors,Color>> +
+(default: $heading_font_color)
+|heading:
+  h2_font_color: [0, 99%, 100%, 0]
+
+|font_family
+|<<fonts,Font family name>> +
+(default: $heading_font_family)
+|heading:
+  h4_font_family: Roboto
+
+|font_size^[1]^
+|<<values,Number>> +
+(default: h1=24; h2=18; h3=16; h4=14; h5=12; h6=10)
+|heading:
+  h6_font_size: $base_font_size * 1.7
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: $heading_font_style)
+|heading:
+  h3_font_style: bold_italic
+
+|text_transform
+|none {vbar} uppercase {vbar} lowercase +
+(default: $heading_text_transform)
+|heading:
+  text_transform: lowercase
+|===
 
-|heading_h<n>_font_size^[1]^
-|<<values,number>>
-|h6_font_size: round($base_font_size * 1.7)
+. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
+. A font size is assigned to each heading level by the base theme.
+If you want the font size of a specific level to be inherited, you must assign the value `null` (or `~` for short).
 
-|heading_h<n>_font_style^[1]^
-|normal, italic, bold, bold_italic
-|h3_font_style: bold_italic
+=== Title Page
 
-|heading_line_height
-|<<values,number>>
-|line_height: 1.2
+The keys in this category control the style of the title page as well as the arrangement and style of the elements on it.
 
-|heading_margin_top
-|<<measurement-units,measurement>>
-|margin_top: $vertical_rhythm * 0.2
+TIP: The title page can be disabled from the document by setting the `notitle` attribute in the document header.
 
-|heading_margin_bottom
-|<<measurement-units,measurement>>
-|margin_bottom: 9.600
+[cols="3,4,5l"]
 |===
+|Key |Value Type |Example
 
-^[1]^ `<n>` may be a number ranging from 1 to 6, representing each of the six heading levels.
+3+|*Key Prefix:* title_page
 
-=== Title page
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: center)
+|title_page:
+  align: right
 
-[cols="3,3,5m"]
-|===
-|Key |Value Type |Example
+|background_color^[1]^
+|<<colors,Color>>
+|title_page:
+  background_color: #eaeaea
 
-|title_page_align
-|left, center, right, justify
-|align: right
+|background_image^[1]^
+|Inline image macro^[2]^
+|title_page:
+  +background_image: image:title.png[]+
 
-|title_page_background_color^[1]^
-|<<colors,color>>
-|background_color: #eaeaea
+|font_color
+|<<colors,Color>>
+|title_page:
+  font_color: #333333
 
-|title_page_background_image^[1]^
-|path (absolute or relative to pdf-stylesdir)
-|+background_image: image:title.png[]+
+|font_family
+|<<fonts,Font family name>>
+|title_page:
+  font_family: Noto Serif
 
-|title_page_logo_align
-|left, center, right
-|logo_align: right
+|font_size
+|<<values,Number>>
+|title_page:
+  font_size: $base_font_size_large
 
-|title_page_logo_image
-|inline image macro
-|+logo_image: image:logo.png[scaledwidth=25%]+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|title_page:
+  font_style: bold
 
-|title_page_logo_top
-|percentage
-|logo_top: 25%
+|line_height
+|<<values,Number>> +
+(default: 1.15)
+|title_page:
+  line_height: 1
 
-|title_page_title_top
-|percentage
-|title_top: 55%
+3+|*Key Prefix:* title_page_logo
 
-|title_page_title_font_size
-|<<values,number>>
-|title_font_size: 27
+|align
+|left {vbar} center {vbar} right
+|title_page:
+  logo:
+    align: right
 
-|title_page_title_font_color
-|<<colors,color>>
-|title_font_color: #999999
+|image
+|Inline image macro^[2]^
+|title_page:
+  logo:
+    +image: image:logo.png[pdfwidth=25%]+
 
-|title_page_title_line_height
-|<<values,number>>
-|title_line_height: 0.9
+|top
+|Percentage +
+(default: 10%)
+|title_page:
+  logo:
+    top: 25%
 
-|title_page_subtitle_font_size
-|<<values,number>>
-|subtitle_font_size: 18
+3+|*Key Prefix:* title_page_title
 
-|title_page_subtitle_font_style
-|normal, italic, bold, bold_italic
-|subtitle_font_style: bold_italic
+|font_color
+|<<colors,Color>>
+|title_page:
+  title:
+    font_color: #999999
 
-|title_page_subtitle_line_height
-|<<values,number>>
-|subtitle_line_height: 1
+|font_family
+|<<fonts,Font family name>>
+|title_page:
+  title:
+    font_family: Noto Serif
 
-|title_page_authors_margin_top
-|<<measurement-units,measurement>>
-|authors_margin_top: 13.125
+|font_size
+|<<values,Number>> +
+(default: 18)
+|title_page:
+  title:
+    font_size: $heading_h1_font_size
 
-|title_page_authors_font_size
-|<<values,number>>
-|authors_font_size: $base_font_size_large
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|title_page:
+  title:
+    font_style: bold
 
-|title_page_authors_font_color
-|<<colors,color>>
-|authors_font_color: #181818
+|line_height
+|<<values,Number>>
+|title_page:
+  title:
+    line_height: 0.9
 
-|title_page_revision_margin_top
-|<<measurement-units,measurement>>
-|revision_margin_top: 13.125
+|top
+|Percentage +
+(default: 40%)
+|title_page:
+  title:
+    top: 55%
+
+3+|*Key Prefix:* title_page_subtitle
+
+|font_color
+|<<colors,Color>>
+|title_page:
+  subtitle:
+    font_color: #181818
+
+|font_family
+|<<fonts,Font family name>>
+|title_page:
+  subtitle:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: 14)
+|title_page:
+  subtitle:
+    font_size: $heading_h3_font_size
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|title_page:
+  subtitle:
+    font_style: bold_italic
+
+|line_height
+|<<values,Number>>
+|title_page:
+  subtitle:
+    line_height: 1
+
+3+|*Key Prefix:* title_page_authors
+
+|font_color
+|<<colors,Color>>
+|title_page:
+  authors:
+    font_color: #181818
+
+|font_family
+|<<fonts,Font family name>>
+|title_page:
+  authors:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>>
+|title_page:
+  authors:
+    font_size: $base_font_size_large
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|title_page:
+  authors:
+    font_style: bold_italic
+
+|margin_top
+|<<measurement-units,Measurement>> +
+(default: 12)
+|title_page:
+  authors:
+    margin_top: 13.125
+
+3+|*Key Prefix:* title_page_revision
+
+|font_color
+|<<colors,Color>>
+|title_page:
+  revision:
+    font_color: #181818
+
+|font_family
+|<<fonts,Font family name>>
+|title_page:
+  revision:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>>
+|title_page:
+  revision:
+    font_size: $base_font_size_small
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|title_page:
+  revision:
+    font_style: bold
+
+|margin_top
+|<<measurement-units,Measurement>>
+|title_page:
+  revision:
+    margin_top: 13.125
 |===
 
-TIP: The title page can be disabled from the document by setting the `notitle` attribute in the document header.
-
-^[1]^ Background colors and images do not currently work when using AsciidoctorJ PDF.
+. 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.
 
 === Block
 
-[cols="3,3,5m"]
+The keys in this category control the spacing around block elements when a more specific setting is not designated.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|block_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|padding: [12, 15, 12, 15]
+3+|*Key Prefix:* block
+
+//|padding
+//|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
+//|block:
+//  padding: [12, 15, 12, 15]
 
-|block_margin_top
-|<<measurement-units,measurement>>
-|margin_top: 0
+|margin_top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|block:
+  margin_top: 6
 
-|block_margin_bottom
-|<<measurement-units,measurement>>
-|margin_bottom: 1
+|margin_bottom
+|<<measurement-units,Measurement>> +
+(default: 12)
+|block:
+  margin_bottom: 6
 |===
 
 Block styles are applied to the following block types:
@@ -1014,587 +1316,979 @@ Block styles are applied to the following block types:
 
 === Caption
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of block captions.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|caption_font_color
-|<<colors,color>>
-|font_color: #333333
-
-|caption_font_family
-|<<fonts,font family name>>
-|font_family: M+ 1mn
-
-|caption_font_size
-|<<values,number>>
-|font_size: 11
+3+|*Key Prefix:* caption
 
-|caption_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: left)
+|caption:
+  align: left
 
-|caption_align
-|left, center, right, justify
-|align: left
-
-|caption_margin_inside
-|<<measurement-units,measurement>>
-|margin_inside: 3
+|font_color
+|<<colors,Color>>
+|caption:
+  font_color: #333333
 
-|caption_margin_outside
-|<<measurement-units,measurement>>
-|margin_outside: 0
+|font_family
+|<<fonts,Font family name>>
+|caption:
+  font_family: M+ 1mn
+
+|font_size
+|<<values,Number>>
+|caption:
+  font_size: 11
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: italic)
+|caption:
+  font_style: italic
+
+|margin_inside
+|<<measurement-units,Measurement>> +
+(default: 4)
+|caption:
+  margin_inside: 3
+
+|margin_outside
+|<<measurement-units,Measurement>> +
+(default: 0)
+|caption:
+  margin_outside: 0
 |===
 
 === Code
 
-[cols="3,3,5m"]
+The keys in this category are used to control the style of literal, listing and source blocks.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|code_font_color
-|<<colors,color>>
-|font_color: #333333
-
-|code_font_family
-|<<fonts,font family name>>
-|font_family: M+ 1mn
-
-|code_font_size
-|<<values,number>>
-|font_size: 11
-
-|code_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
-
-|code_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|padding: 11
-
-|code_line_height
-|<<values,number>>
-|line_height: 1.25
-
-|code_background_color
-|<<colors,color>>
-|background_color: #f5f5f5
-
-|code_border_color
-|<<colors,color>>
-|border_color: #cccccc
-
-|code_border_radius
-|<<values,number>>
-|border_radius: 4
+3+|*Key Prefix:* code
+
+|background_color
+|<<colors,Color>>
+|code:
+  background_color: #f5f5f5
+
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|code:
+  border_color: #cccccc
+
+|border_radius
+|<<values,Number>> +
+(default: 0)
+|code:
+  border_radius: 4
+
+|border_width
+|<<values,Number>> +
+(default: 0.5)
+|code:
+  border_width: 0.75
+
+|font_color
+|<<colors,Color>>
+|code:
+  font_color: #333333
 
-|code_border_width
-|<<values,number>>
-|border_width: 0.75
+|font_family
+|<<fonts,Font family name>> +
+(default: Courier)
+|code:
+  font_family: M+ 1mn
+
+|font_size
+|<<values,Number>> +
+(default: 10.5)
+|code:
+  font_size: 11
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|code:
+  font_style: italic
+
+|line_height
+|<<values,Number>> +
+(default: 1.2)
+|code:
+  line_height: 1.25
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: 9)
+|code:
+  padding: 11
 |===
 
 === Blockquote
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of quote blocks.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|blockquote_font_color
-|<<colors,color>>
-|font_color: #333333
-
-|blockquote_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
-
-|blockquote_font_size
-|<<values,number>>
-|font_size: 13
+3+|*Key Prefix:* blockquote
 
-|blockquote_font_style
-|normal, italic, bold, bold_italic
-|font_style: bold
+|border_width
+|<<values,Number>> +
+(default: 4)
+|blockquote:
+  border_width: 5
 
-|blockquote_border_width
-|<<values,number>>
-|border_width: 5
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|blockquote:
+  border_color: #eeeeee
 
-|blockquote_border_color
-|<<colors,color>>
-|border_color: #eeeeee
-
-|blockquote_cite_font_size
-|<<values,number>>
-|cite_font_size: 9
+|font_color
+|<<colors,Color>>
+|blockquote:
+  font_color: #333333
 
-|blockquote_cite_font_color
-|<<colors,color>>
-|cite_font_color: #999999
+|font_family
+|<<fonts,Font family name>>
+|blockquote:
+  font_family: Noto Serif
 
-|blockquote_cite_font_family
-|<<fonts,font family name>>
-|cite_font_family: Noto Serif
+|font_size
+|<<values,Number>>
+|blockquote:
+  font_size: 13
 
-|blockquote_cite_font_style
-|normal, italic, bold, bold_italic
-|cite_font_style: bold
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|blockquote:
+  font_style: bold
 
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [6, 12, -6, 14])
+|blockquote:
+  padding: [5, 10, -5, 12]
+
+3+|*Key Prefix:* blockquote_cite
+
+|font_size
+|<<values,Number>>
+|blockquote:
+  cite:
+    font_size: 9
+
+|font_color
+|<<colors,Color>>
+|blockquote:
+  cite:
+    font_color: #999999
+
+|font_family
+|<<fonts,Font family name>>
+|blockquote:
+  cite:
+    font_family: Noto Serif
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|blockquote:
+  cite:
+    font_style: bold
 |===
 
 === Sidebar
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of sidebar blocks.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|sidebar_border_color
-|<<colors,color>>
-|border_color: #ffffff
-
-|sidebar_border_radius
-|<<values,number>>
-|border_radius: 4
-
-|sidebar_border_width
-|<<values,number>>
-|border_width: 0.5
-
-|sidebar_background_color
-|<<colors,color>>
-|background_color: #eeeeee
-
-|sidebar_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|padding: [12, 15, 0, 15]
-
-|sidebar_title_align
-|left, center, right, justify
-|title_align: center
+3+|*Key Prefix:* sidebar
+
+|background_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|sidebar:
+  background_color: #eeeeee
+
+|border_color
+|<<colors,Color>>
+|sidebar:
+  border_color: #ffffff
+
+|border_radius
+|<<values,Number>>
+|sidebar:
+  border_radius: 4
+
+|border_width
+|<<values,Number>>
+|sidebar:
+  border_width: 0.5
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [12, 12, 0, 12])
+|sidebar:
+  padding: [12, 15, 0, 15]
+
+3+|*Key Prefix:* sidebar_title
+
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: center)
+|sidebar:
+  title:
+    align: center
 
-|sidebar_title_font_color
-|<<colors,color>>
-|title_font_color: #333333
+|font_color
+|<<colors,Color>>
+|sidebar:
+  title:
+    font_color: #333333
 
-|sidebar_title_font_family
-|<<fonts,font family name>>
-|title_font_family: Noto Serif
+|font_family
+|<<fonts,Font family name>>
+|sidebar:
+  title:
+    font_family: Noto Serif
 
-|sidebar_title_font_size
-|<<values,number>>
-|title_font_size: 13
+|font_size
+|<<values,Number>>
+|sidebar:
+  title:
+    font_size: 13
 
-|sidebar_title_font_style
-|normal, italic, bold, bold_italic
-|title_font_style: bold
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: bold)
+|sidebar:
+  title:
+    font_style: bold
 |===
 
 === Example
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of example blocks.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|example_border_color
-|<<colors,color>>
-|border_color: #eeeeee
-
-|example_border_radius
-|<<values,number>>
-|border_radius: 4
-
-|example_border_width
-|<<values,number>>
-|border_width: 0.75
-
-|example_background_color
-|<<colors,color>>
-|background_color: #fffef7
+3+|*Key Prefix:* example
+
+|background_color
+|<<colors,Color>>
+|example:
+  background_color: #fffef7
+
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|example:
+  border_color: #eeeeee
+
+|border_radius
+|<<values,Number>> +
+(default: 0)
+|example:
+  border_radius: 4
+
+|border_width
+|<<values,Number>> +
+(default: 0.5)
+|example:
+  border_width: 0.75
 |===
 
 === Admonition
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of admonition blocks and the icon used for each admonition type.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|admonition_border_color
-|<<colors,color>>
-|border_color: #eeeeee
-
-|admonition_border_width
-|<<values,number>>
-|border_width: 0.5
-
-|admonition_icon_<name>_name^[1]^
-|string^[2]^
-|admonition_icon_tip_name: fa-fire
-
-|admonition_icon_<name>_stroke_color
-|<<colors,color>>
-|admonition_icon_tip_stroke_color: ff0000
-
-|admonition_icon_<name>_size
-|<<values,number>> +
+3+|*Key Prefix:* admonition
+
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|admonition:
+  border_color: #eeeeee
+
+|border_width
+|<<values,Number>> +
+(default: 0.5)
+|admonition:
+  border_width: 0.5
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: [0, 12, 0, 12])
+|admonition:
+  padding: [0, 12, 0, 12]
+
+3+|*Key Prefix:* admonition_icon
+
+|<name>_name^[1]^
+|String^[2]^
+|admonition:
+  icon:
+    tip:
+      name: fa-fire
+
+|<name>_stroke_color^[1]^
+|<<colors,Color>>
+|admonition:
+  icon:
+    tip:
+      stroke_color: ff0000
+
+|<name>_size^[1]^
+|<<values,Number>> +
 (default: 24)
-|admonition_icon_tip_size: 24
+|admonition:
+  icon:
+    tip:size: 24
 |===
 
-^[1]^ `<name>` can be `note`, `tip`, `warning`, `important` or `caution`. +
-^[2]^ See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository] for a list of valid names.
+. `<name>` can be `note`, `tip`, `warning`, `important` or `caution`. +
+. See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository] for a list of valid names.
 The prefix (e.g., `fa-`) determines which font set to use.
 
 === Image
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement of block images.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|image_align
-|left, center, right
-|align: left
+3+|*Key Prefix:* image
+
+|align
+|left {vbar} center {vbar} right +
+(default: left)
+|image:
+  align: left
 |===
 
 === Lead
 
-[cols="3,3,5m"]
+The keys in this category control the styling of lead paragraphs.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|lead_font_size
-|<<values,number>>
-|font_size: 13
+3+|*Key Prefix:* lead
+
+|font_size
+|<<values,Number>> +
+(default: 13.5)
+|lead:
+  font_size: 13
 
-|lead_line_height
-|<<values,number>>
-|line_height: 1.4
+|line_height
+|<<values,Number>> +
+(default: 1.4)
+|lead:
+  line_height: 1.4
 |===
 
 === Abstract
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of the abstract.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|abstract_font_color
-|<<colors,color>>
-|font_color: #5c6266
-
-|abstract_font_size
-|<<values,number>>
-|font_size: 13
-
-|abstract_line_height
-|<<values,number>>
-|line_height: 1.4
-
-|abstract_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
+3+|*Key Prefix:* abstract
+
+|font_color
+|<<colors,Color>>
+|abstract:
+  font_color: #5c6266
+
+|font_size
+|<<values,Number>> +
+(default: 13.5)
+|abstract:
+  font_size: 13
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|abstract:
+  font_style: italic
+
+|line_height
+|<<values,Number>> +
+(default: 1.4)
+|abstract:
+  line_height: 1.4
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: 0)
+|abstract:
+  padding: [0, 12, 0, 12]
 |===
 
-=== Thematic break
+=== Thematic Break
+
+The keys in this category control the style of thematic breaks (aka horizontal rules).
 
-[cols="3,3,5m"]
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|thematic_break_border_color
-|<<colors,color>>
-|border_color: #eeeeee
+3+|*Key Prefix:* thematic_break
+
+|border_color
+|<<colors,Color>> +
+(default: #eeeeee)
+|thematic_break:
+  border_color: #eeeeee
 
-|thematic_break_border_style
-|solid, double, dashed, dotted +
+|border_style
+|solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
-|border_style: dashed
+|thematic_break:
+  border_style: dashed
+
+|border_width
+|<<measurement-units,Measurement>> +
+(default: 0.5)
+|thematic_break:
+  border_width: 0.5
+
+|margin_top
+|<<measurement-units,Measurement>>
+|thematic_break:
+  margin_top: 6
+
+|margin_bottom
+|<<measurement-units,Measurement>>
+|thematic_break:
+  margin_bottom: 18
+|===
 
-|thematic_break_border_width
-|<<measurement-units,measurement>>
-|border_width: 0.5
+=== Description List
 
-|thematic_break_margin_top
-|<<measurement-units,measurement>>
-|margin_top: 6
+The keys in this category control the arrangement and style of definition list items (terms and descriptions).
 
-|thematic_break_margin_bottom
-|<<measurement-units,measurement>>
-|margin_bottom: 18
+[cols="3,4,5l"]
 |===
+|Key |Value Type |Example
 
-=== Description list
+3+|*Key Prefix:* description_list
 
-[cols="3,3,5m"]
-|===
-|Key |Value Type |Example
+|term_font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|description_list:
+  term_font_style: italic
 
-|description_list_term_font_style
-|normal, italic, bold, bold_italic
-|term_font_style: italic
+|term_spacing
+|<<measurement-units,Measurement>> +
+(default: 4)
+|description_list:
+  term_spacing: 5
 
-|description_list_description_indent
-|<<values,number>>
-|description_indent: 15
+|description_indent
+|<<values,Number>> +
+(default: 30)
+|description_list:
+  description_indent: 15
 |===
 
+=== Outline List
 
-=== Outline list
+The keys in this category control the arrangement and style of outline list items.
 
-[cols="3,3,5m"]
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|outline_list_indent
-|<<measurement-units,measurement>>
-|list_indent: 40
+3+|*Key Prefix:* outline_list
+
+|indent
+|<<measurement-units,Measurement>> +
+(default: 30)
+|outline_list:
+  indent: 40
 
-|outline_list_item_spacing
-|<<measurement-units,measurement>>
-|item_spacing: 4
+|item_spacing
+|<<measurement-units,Measurement>> +
+(default: 6)
+|outline_list:
+  item_spacing: 4
 |===
 
 === Table
 
-[cols="3,3,5m"]
+The keys in this category control the arrangement and style of tables and table cells.
+
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|table_background_color
-|<<colors,color>>
-|background_color: #ffffff
-
-|table_head_background_color
-|<<colors,color>>
-|background_color: #f0f0f0
+3+|*Key Prefix:* table
+
+|background_color
+|<<colors,Color>>
+|table:
+  background_color: #ffffff
+
+|border_color
+|<<colors,Color>> +
+(default: #000000)
+|table:
+  border_color: #dddddd
+
+|border_width
+|<<values,Number>> +
+(default: 0.5)
+|table:
+  border_width: 0.5
+
+|font_color
+|<<colors,Color>> +
+(default: $base_font_color)
+|table:
+  font_color: #333333
 
-|table_even_row_background_color
-|<<colors,color>>
-|even_row_background_color: #f9f9f9
+|font_family
+|<<fonts,Font family name>>
+|table:
+  font_family: Helvetica
+
+|font_size
+|<<values,Number>>
+|table:
+  font_size: 9.5
+
+|grid_color
+|<<colors,Color>> +
+(default: $table_border_color)
+|table:
+  grid_color: #eeeeee
+
+|grid_width
+|<<values,Number>> +
+(default: $table_border_width)
+|table:
+  grid_width: 0.5
+
+3+|*Key Prefix:* table_head
+
+|background_color
+|<<colors,Color>> +
+(default: $table_background_color)
+|table:
+  head:
+    background_color: #f0f0f0
+
+|font_color
+|<<colors,Color>> +
+(default: $table_font_color)
+|table:
+  head:
+    font_color: #333333
+
+|font_family
+|<<fonts,Font family name>> +
+(default: $table_font_family)
+|table:
+  head:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: $table_font_size)
+|table:
+  head:
+    font_size: 10
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: bold)
+|table:
+  head:
+    font_style: normal
+
+|text_transform
+|none {vbar} uppercase {vbar} lowercase +
+(default: none)
+|table:
+  head:
+    text_transform: uppercase
+
+3+|*Key Prefix:* table_foot
+
+|background_color
+|<<colors,Color>> +
+(default: $table_background_color)
+|table:
+  foot:
+    background_color: #f0f0f0
+
+|font_color
+|<<colors,Color>> +
+(default: $table_font_color)
+|table:
+  foot:
+    font_color: #333333
+
+|font_family
+|<<fonts,Font family name>> +
+(default: $table_font_family)
+|table:
+  foot:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: $table_font_size)
+|table:
+  foot:
+    font_size: 10
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic +
+(default: normal)
+|table:
+  foot:
+    font_style: italic
+
+3+|*Key Prefix:* table_<parity>_row^[1]^
+
+|background_color
+|<<colors,Color>>
+|table:
+  even_row:
+    background_color: #f9f9f9
+
+3+|*Key Prefix:* table_cell
+
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
+(default: 2)
+|table:
+  cell:
+    padding: [3, 3, 6, 3]
+
+3+|*Key Prefix:* table_header_cell
+
+|align
+|left {vbar} center {vbar} right
+|table:
+  header_cell:
+    align: center
+
+|background_color
+|<<colors,Color>>
+|table:
+  header_cell:
+    background_color: #f0f0f0
+
+|font_color
+|<<colors,Color>>
+|table:
+  header_cell:
+    font_color: #1a1a1a
+
+|font_family
+|<<fonts,Font family name>>
+|table:
+  header_cell: 
+    font_family: Noto Sans
+
+|font_size
+|<<values,Number>>
+|table:
+  header_cell:
+    font_size: 12
+
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|table:
+  header_cell:
+    font_style: italic
+|===
 
-|table_foot_background_color
-|<<colors,color>>
-|foot_background_color: #f0f0f0
+. `<parity>` can be `odd` (odd rows) or `even` (even rows).
 
-|table_header_cell_align
-|left, center, right
-|align: center
+[[key-toc]]
+=== Table of Contents
 
-|table_header_cell_background_color
-|<<colors,color>>
-|background_color: #f0f0f0
+The keys in this category control the arrangement and style of the table of contents.
 
-|table_header_cell_font_color
-|<<colors,color>>
-|font_color: #1a1a1a
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
 
-|table_header_cell_font_family
-|<<fonts,font family name>>
-|font_family: Noto Sans
+3+|*Key Prefix:* toc
 
-|table_header_cell_font_size
-|<<values,number>>
-|font_size: 12
+|font_color
+|<<colors,Color>>
+|toc:
+  font_color: #333333
 
-|table_header_cell_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
+|font_family
+|<<fonts,Font family name>>
+|toc:
+  font_family: Noto Serif
 
-|table_border_color
-|<<colors,color>>
-|border_color: #dddddd
+|font_size
+|<<values,Number>>
+|toc:
+  font_size: 9
 
-|table_border_width
-|<<values,number>>
-|border_width: 0.5
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|toc:
+  font_style: bold
 
-|table_cell_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|cell_padding: [3, 3, 6, 3]
-|===
+|line_height
+|<<values,Number>> +
+(default: 1.4)
+|toc:
+  line_height: 1.5
 
-[[key-toc]]
-=== Table of contents
+|indent
+|<<measurement-units,Measurement>> +
+(default: 15)
+|toc:
+  indent: 20
 
-[cols="3,3,5m"]
-|===
-|Key |Value Type |Example
+|margin_top
+|<<measurement-units,Measurement>>
+|toc:
+  margin_top: 0
 
-|toc_dot_leader_content
-|double-quoted string
-|dot_leader_content: ". "
+3+|*Key Prefix:* toc_h<n>^[1]^
 
-|toc_dot_leader_color
-|<<colors,color>>
-|dot_leader_color: #999999
+|font_color
+|<<colors,Color>>
+|toc:
+  h3_font_color: #999999
 
-|toc_font_color
-|<<colors,color>>
-|font_color: #333333
+3+|*Key Prefix:* toc_title^[2]^
 
-|toc_h<n>_font_color
-|<<colors,color>>
-|h3_font_color: #999999
+|align
+|left {vbar} center {vbar} right {vbar} justify +
+(default: left)
+|toc:
+  title:
+    align: center
 
-|toc_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
+3+|*Key Prefix:* toc_dot_leader
 
-|toc_font_size
-|<<values,number>>
-|font_size: 9
+|content
+|Quoted string
+|toc:
+  dot_leader:
+    content: ". "
 
-|toc_font_style
-|normal, italic, bold, bold_italic
-|font_style: bold
+|color
+|<<colors,Color>>
+|toc:
+  dot_leader:
+    color: #999999
+|===
 
-|toc_line_height
-|number
-|line_height: 1.5
+. `<n>` is a number ranging from 1 to 6, representing each of the six heading levels.
+. The `toc_title` keys inherit from level-2 heading styles, except where noted.
 
-|toc_indent
-|<<measurement-units,measurement>>
-|indent: 20
+[#running-content]
+=== Running Header & Footer
 
-|toc_margin_top
-|<<measurement-units,measurement>>
-|indent: 20
-|===
+The keys in this category control the arrangement and style of running header and footer content.
 
-=== Running header & footer
+TIP: If you defined running header and footer content in your theme, you can still disable this content per document by setting the `noheader` and `nofooter` document attributes, respectively.
 
-[cols="3,3,5m"]
+[cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
-|header_background_color
-|<<colors,color>>
-|background_color: #eeeeee
+3+|*Key Prefix:* header
+
+|background_color
+|<<colors,Color>>
+|header:
+  background_color: #eeeeee
 
-|header_border_color
-|<<colors,color>>
-|border_color: #dddddd
+|border_color
+|<<colors,Color>>
+|header:
+  border_color: #dddddd
 
-|header_border_style
-|solid, double, dashed, dotted +
+|border_style
+|solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
-|border_style: dashed
+|header:
+  border_style: dashed
 
-|header_border_width
-|<<measurement-units,measurement>>
-|border_width: 0.25
+|border_width
+|<<measurement-units,Measurement>>
+|header:
+  border_width: 0.25
 
-|header_font_color
-|<<colors,color>>
-|font_color: #333333
+|font_color
+|<<colors,Color>>
+|header:
+  font_color: #333333
 
-|header_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
+|font_family
+|<<fonts,Font family name>>
+|header:
+  font_family: Noto Serif
 
-|header_font_size
-|<<values,number>>
-|font_size: 9
+|font_size
+|<<values,Number>>
+|header:
+  font_size: 9
 
-|header_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|header:
+  font_style: italic
 
-|header_height
-|<<measurement-units,measurement>>
-|height: 0.75in
+|height
+|<<measurement-units,Measurement>>
+|header:
+  height: 0.75in
 
-|header_line_height
-|<<values,number>> +
+|line_height
+|<<values,Number>> +
 (default: $base_line_height)
-|height: 1.2
+|header:
+  line_height: 1.2
 
-|header_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|padding: [0, 3, 0, 3]
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
+|header:
+  padding: [0, 3, 0, 3]
 
-|header_image_vertical_align
-|top, middle, bottom, <<measurement-units,measurement>>
-|image_vertical_align: 4
+|image_vertical_align
+|top {vbar} middle {vbar} bottom {vbar} <<measurement-units,Measurement>>
+|header:
+  image_vertical_align: 4
 
-|header_vertical_align
-|top, middle, bottom
-|vertical_align: center
+|vertical_align
+|top {vbar} middle {vbar} bottom
+|header:
+  vertical_align: center
+
+|<face>_content_<position>^[1]^
+|Quoted string
+|header:
+  recto_content:
+    left: '\{page-number}'
 
-|header_<side>_content_<align>^[1]^
-|quoted string
-|right: '\{page-number}'
+3+|*Key Prefix:* footer
 
-|footer_background_color
-|<<colors,color>>
-|background_color: #eeeeee
+|background_color
+|<<colors,Color>>
+|footer:
+  background_color: #eeeeee
 
-|footer_border_color
-|<<colors,color>>
-|border_color: #dddddd
+|border_color
+|<<colors,Color>>
+|footer:
+  border_color: #dddddd
 
-|footer_border_style
-|solid, double, dashed, dotted +
+|border_style
+|solid {vbar} double {vbar} dashed {vbar} dotted +
 (default: solid)
-|border_style: dashed
+|footer:
+  border_style: dashed
 
-|footer_border_width
-|<<measurement-units,measurement>>
-|border_width: 0.25
+|border_width
+|<<measurement-units,Measurement>>
+|footer:
+  border_width: 0.25
 
-|footer_font_color
-|<<colors,color>>
-|font_color: #333333
+|font_color
+|<<colors,Color>>
+|footer:
+  font_color: #333333
 
-|footer_font_family
-|<<fonts,font family name>>
-|font_family: Noto Serif
+|font_family
+|<<fonts,Font family name>>
+|footer:
+  font_family: Noto Serif
 
-|footer_font_size
-|<<values,number>>
-|font_size: 9
+|font_size
+|<<values,Number>>
+|footer:
+  font_size: 9
 
-|footer_font_style
-|normal, italic, bold, bold_italic
-|font_style: italic
+|font_style
+|normal {vbar} italic {vbar} bold {vbar} bold_italic
+|footer:
+  font_style: italic
 
-|footer_height
-|<<measurement-units,measurement>>
-|height: 0.75in
+|height
+|<<measurement-units,Measurement>>
+|footer:
+  height: 0.75in
 
-|footer_line_height
-|<<values,number>> +
+|line_height
+|<<values,Number>> +
 (default: $base_line_height)
-|height: 1.2
+|footer:
+  line_height: 1.2
 
-|footer_padding
-|<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
-|padding: [0, 3, 0, 3]
+|padding
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
+|footer:
+  padding: [0, 3, 0, 3]
 
-|footer_image_vertical_align
-|top, middle, bottom, <<measurement-units,measurement>>
-|image_vertical_align: 4
+|image_vertical_align
+|top {vbar} middle {vbar} bottom {vbar} <<measurement-units,Measurement>>
+|footer:
+  image_vertical_align: 4
 
-|footer_vertical_align
-|top, middle, bottom
-|vertical_align: top
+|vertical_align
+|top {vbar} middle {vbar} bottom
+|footer:
+  vertical_align: top
 
-|footer_<side>_content_<align>^[1]^
-|quoted string
-|center: '\{page-number}'
+|<face>_content_<position>^[1]^
+|Quoted string
+|footer:
+  verso_content:
+    center: '\{page-number}'
 |===
 
-^[1]^ `<side>` can be `recto` (odd pages) or `verso` (even pages).
-`<align>` can be `left`, `center` or `right`.
+. `<face>` can be `recto` (odd pages) or `verso` (even pages).
+`<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.
 
 TIP: The running header and footer can be disabled from the document by setting the `noheader` and the `nofooter` attributes, respectively, in the document header.
 
-NOTE: If content is not specified for the running footer, the page number (i.e., `+{page-number}+`) will be shown on the left side on verso pages and the right side on recto pages.
+NOTE: If content is not specified for the running footer, the page number (i.e., `\{page-number}`) will be shown on the left side on verso pages and the right side on recto pages.
 
 NOTE: The background color spans the width of the page.
 When a background color is specified, the border also spans the width of the page.
 
-==== Attribute references
+==== Attribute References
 
 You can use _any_ attribute defined in your AsciiDoc document in the content of the running header and footer.
 In addition, the following attributes are also available when defining the content keys in the footer:
@@ -1607,7 +2301,7 @@ In addition, the following attributes are also available when defining the conte
 * section-title
 * section-or-chapter-title
 
-You can also built-in AsciiDoc text replacements like `+(C)+` or numeric character references like `+&#169;+`.
+You can also built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+&#169;+` and inline formatting (e.g., bold, italic, monospace).
 
 Here's an example that shows how attributes and replacements can be used in the running footer:
 
@@ -1619,7 +2313,7 @@ header:
   recto_content:
     center: '(C) ACME -- v{revnumber}, {docdate}'
   verso_content:
-    center: $header_recto_content
+    center: $header_recto_content_center
 footer:
   height: 0.75in
   line_height: 1
@@ -1631,7 +2325,7 @@ footer:
 
 You can split the content value across multiple lines using YAML's multiline string syntax.
 In this case, the single quotes around the string are not necessary.
-To force a hard line break in the output, add [x-]+{space}{plus}+ to the end of the line in normal AsciiDoc fashion.
+To force a hard line break in the output, add `{sp}+` to the end of the line in normal AsciiDoc fashion.
 
 [source,yaml]
 ----
@@ -1660,11 +2354,11 @@ It cannot be combined with text.
 
 Here's an example of how to use an image in the running header (which also applies for the footer).
 
-[source,yaml]
+[source,yaml,subs=attributes+]
 ----
 header:
   height: 0.75in
-  image_vertical_align: 2 # <1>
+  image_vertical_align: 2 {conum-guard-yaml} <1>
   recto_content:
     center: image:footer-logo.png[width=80]
   verso_content:
@@ -1676,7 +2370,7 @@ CAUTION: The image must fit in the allotted space for the running header or foot
 Otherwise, you will run into layout issues.
 Adjust the width attribute accordingly.
 
-== Applying your theme
+== Applying Your Theme
 
 After creating a theme, you'll need to tell Asciidoctor PDF where to find it.
 This is done using AsciiDoc attributes.
@@ -1728,3 +2422,57 @@ However, in the future, this may change so that paths are resolved relative to t
 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
+
+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.
+
+* https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-with-theme-example[Maven Example]
+* https://github.com/asciidoctor/asciidoctor-gradle-examples/tree/master/asciidoc-to-pdf-with-theme-example[Gradle Example]
+
+== Theme-Related Document Attributes
+
+There are various settings in the theme you control using document attributes.
+These settings override equivalent keys defined in the theme file, where applicable.
+
+[cols="2,3,6m"]
+|===
+|Attribute |Value Type |Example
+
+|autofit-option
+|flag (default: _not set_)
+|:autofit-option:
+
+|chapter-label
+|string (default: Chapter)
+|:chapter-label: Chapter
+
+|<face>-cover-image
+|inline image macro (target is relative to `imagesdir`; can be image or PDF file)
+|+:front-cover-image: image:front-cover.pdf[]+
+
+|pagenums^[2]^
+|flag (default: _set_)
+|:pagenums:
+
+//|pdf-page-layout
+//|portrait, landscape
+//|:pdf-page-layout: landscape
+
+|pdf-page-size
+|https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[named size^], <<measurement-units,measurement dimensions>> (width x height)
+|:pdf-page-size: 6in x 9in
+
+|title-logo-image
+|inline image macro (path is relative to `imagesdir`; can be image or PDF file)
+|+:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]+
+|===
+
+. `<face>` can be `front` or `back`.
+. 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.
+
+////
+== Resources for Extending Asciidoctor PDF
+
+* http://www.sitepoint.com/hackable-pdf-typesetting-in-ruby-with-prawn[Hackable PDF typesetting in Ruby with Prawn]
+////