asciidoctor-pdf 1.5.0.alpha.7 → 1.5.0.alpha.8

data/data/themes/default-theme.yml

@@ -1,16 +1,16 @@
 font:
   catalog:
-    NotoSerif:
+    Noto Serif:
       normal: notoserif-regular-latin.ttf
       bold: notoserif-bold-latin.ttf
       italic: notoserif-italic-latin.ttf
       bold_italic: notoserif-bolditalic-latin.ttf
-    Mplus1mn:
+    M+ 1mn:
       normal: mplus1mn-regular-ascii-conums.ttf
       bold: mplus1mn-bold-ascii.ttf
       italic: mplus1mn-italic-ascii.ttf
       bold_italic: mplus1mn-bolditalic-ascii.ttf
-    Mplus1pMultilingual:
+    M+ 1p Fallback:
       normal: mplus1p-regular-multilingual.ttf
       bold: mplus1p-regular-multilingual.ttf
       italic: mplus1p-regular-multilingual.ttf
@@ -18,7 +18,7 @@ font:
   fallbacks:
     # NOTE M+ 1p doesn't support all CJK characters, but it at least has some coverage
     # NOTE M+ 1p provides the arrows for ->, <-, => and <=
-    - Mplus1pMultilingual
+    - M+ 1p Fallback
 page:
   background_color: ffffff
   layout: portrait
@@ -35,7 +35,7 @@ base:
   # color as CMYK array (approximated)
   #font_color: [0, 0, 0, 0.92]
   #font_color: [0, 0, 0, 92%]
-  font_family: NotoSerif
+  font_family: Noto Serif
   # choose one of these font_size/line_height_length combinations
   #font_size: 14
   #line_height_length: 20
@@ -45,13 +45,14 @@ base:
   #line_height_length: 16
   font_size: 10.5
   #line_height_length: 15
-  # correct line height for NotoSerif metrics
+  # correct line height for Noto Serif metrics
   line_height_length: 12
   #font_size: 11.25
   #line_height_length: 18
   line_height: $base_line_height_length / $base_font_size
   font_size_large: round($base_font_size * 1.25)
   font_size_small: round($base_font_size * 0.85)
+  font_size_min: $base_font_size * 0.75
   font_style: normal
   align: justify
   border_radius: 4
@@ -59,7 +60,7 @@ base:
   border_color: eeeeee
 # FIXME vertical_rhythm is weird; we should think in terms of ems
 #vertical_rhythm: $base_line_height_length * 2 / 3
-# correct line height for NotoSerif metrics
+# correct line height for Noto Serif metrics
 vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
 link:
@@ -67,7 +68,7 @@ link:
 # literal is currently used for inline monospaced in prose and table cells
 literal:
   font_color: b12146
-  font_family: Mplus1mn
+  font_family: M+ 1mn
 heading:
   #font_color: 181818
   font_color: $base_font_color
@@ -82,7 +83,7 @@ heading:
   h6_font_size: $base_font_size_small
   font_style: bold
   #line_height: 1.4
-  # correct line height for NotoSerif metrics
+  # correct line height for Noto Serif metrics
   line_height: 1.2
   margin_top: $vertical_rhythm * 0.2
   margin_bottom: $vertical_rhythm * 0.8
@@ -115,7 +116,7 @@ caption:
   margin_outside: 0
 code:
   font_color: $base_font_color
-  #font_family: LiberationMono
+  #font_family: Liberation Mono
   #font_size: floor($base_font_size * 0.9)
   #font_size: 10
   #padding: [9.5, 9.5, 9.5, 9.5]
@@ -139,7 +140,7 @@ blockquote:
   cite_font_size: $base_font_size_small
   cite_font_color: 999999
 sidebar:
-  border_color: ffffff
+  border_color: $page_background_color
   border_radius: $base_border_radius
   border_width: $base_border_width
   background_color: eeeeee
@@ -157,7 +158,7 @@ admonition:
   border_color: $base_border_color
   border_width: $base_border_width
 conum:
-  font_family: Mplus1mn
+  font_family: M+ 1mn
   font_color: $literal_font_color
   font_size: $base_font_size
   line_height: 4 / 3
@@ -188,8 +189,9 @@ outline_list:
   indent: $horizontal_rhythm * 1.5
   # NOTE item_spacing applies to list items that do not have complex content
   item_spacing: $vertical_rhythm / 2
+  #marker_font_color: 404040
 table:
-  background_color: ffffff
+  background_color: $page_background_color
   #head_background_color: <hex value>
   #head_font_color: $base_font_color
   even_row_background_color: f9f9f9

data/docs/theme-schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Theme Definition",
+  "description": "A JSON schema for describing the available keys and value types for an Asciidoctor PDF theme. Status: Incomplete; early draft.",
+  "definitions": {
+    // FIXME add RGB and CMYK arrays
+    "color": {
+      "type": "string",
+      "pattern": "^#?[a-fA-F0-9]{3,6}$"
+    },
+    "font_style": {
+      "type": "string",
+      "enum": ["normal", "bold", "italic", "bold_italic"]
+    },
+    "measurement": {
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^[0-9]+(?:\\.[0-9]+)?(?:in|mm|cm|pt)?$"
+        },
+        {
+          // FIXME technically, numbers < 0 must have a leading 0 (e.g., 0.8)
+          "type": "number"
+        }
+      ]
+    },
+    "text_alignment": {
+      "type": "string",
+      "enum": ["left", "center", "right", "justify"]
+    }
+  },
+  "type": "object",
+  "properties": {
+    "page_background_color": {
+      "$ref": "#/definitions/color",
+      "default": "#FFFFFF"
+    },
+    "page_background_image": {
+      "type": "string"
+    },
+    "page_layout": {
+      "type": "string",
+      "enum": ["portrait", "landscape"],
+      "default": "portrait"
+    },
+    "page_margin": {
+      "type": "array",
+      "minItems": 4,
+      "maxItems": 4,
+      "items": {
+        "$ref": "#/definitions/measurement"
+      },
+      "additionalItems": false
+    },
+    "page_size": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["A4", "Executive", "Folio", "Legal", "Letter", "Tabloid"]
+        },
+        {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "$ref": "#/definitions/measurement"
+          }
+        }
+      ],
+      "default": "Letter"
+    },
+    "base_align": {
+      "$ref": "#/definitions/text_alignment",
+      "default": "left"
+    },
+    "base_border_color": {
+      "$ref": "#/definitions/color"
+    },
+    "base_border_radius": {
+      "type": "number"
+    },
+    "base_border_width": {
+      "type": "number"
+    },
+    "base_font_color": {
+      "$ref": "#/definitions/color",
+      "default": "#000000"
+    },
+    "base_font_family": {
+      "type": "string",
+      "default": "Helvetica"
+    },
+    "base_font_size": {
+      "type": "number",
+      "default": 12
+    },
+    "base_font_style": {
+      "$ref": "#/definitions/font_style",
+      "default": "normal"
+    },
+    "base_line_height": {
+      "type": "number"
+    },
+    "base_line_height_length": {
+      "$ref": "#/definitions/measurement"
+    },
+    "base_font_size_large": {
+      "type": "number"
+    },
+    "base_font_size_small": {
+      "type": "number"
+    }
+  }
+}

data/docs/theming-guide.adoc

@@ -8,14 +8,10 @@ Dan Allen <https://github.com/mojavelinux>
 
 ////
 Topics remaining to document:
-* transparent color
-* additional fonts provided by Asciidoctor PDF
-* images
-* title page layout
-* title image
-* title page background image
-* keys
-* how to apply the theme
+* document which attributes can be set in document (pdf-page-size, front-cover-image, back-cover-image, etc)
+* 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.
@@ -24,13 +20,26 @@ This document explains how the theming system works, how to define a custom them
 
 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.
 
-Like CSS, themes have both selectors and properties, but only a fraction of what CSS supports.
-Unlike CSS, all selectors are implicit (e.g., `heading`), so you customize the theme primarily by manipulating pre-defined property values (e.g., `font_color`).
+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`).
+
+[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.
+====
 
 A theme (or style) 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.
@@ -67,8 +76,8 @@ outline_list:
   indent: $base_font_size * 1.5
 ----
 
-When creating a new theme, you only have to define the keys you want to override from the base theme.
-The converter uses the information from this map to help construct the PDF.
+When creating a new theme, you only have to define the keys you want to override from the base theme (PENDING, see https://github.com/asciidoctor/asciidoctor-pdf/issues/132[#132]).
+The converter uses the information from the theme map to help construct the PDF.
 All the available keys are documented in <<keys>>.
 
 Keys may be nested to an arbitrary depth to eliminate redundant prefixes (an approach inspired by SASS).
@@ -123,7 +132,7 @@ 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
-* Number (integer or float) with optional units
+* Number (integer or float) with optional units (default unit is points)
 * Array
   - Color as RGB array (e.g., [51, 51, 51])
   - Color CMYK array (e.g., [50, 100, 0, 0])
@@ -138,7 +147,7 @@ Note that keys almost always require a value of a specific type, as documented i
 
 Like CSS, inheritance is a key feature in the Asciidoctor PDF theme language.
 For many of the properties, if a key is not specified, the key inherits the value applied to the parent content in the content hierarchy.
-This behavior saves you from having to explicitly specify properties unless you want to override the inherited value.
+This behavior saves you from having to specify properties unless you want to override the inherited value.
 
 The following keys are inherited:
 
@@ -160,7 +169,7 @@ Headings are special in that they inherit starting from a specific heading level
 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 (`$`) (e.g., `$base_font_size`).
 Any qualified key that has already been defined can be referenced in the value of another key.
-(As soon as the key is assigned, it's available to be used as a variable).
+(In order words, as soon as the key is assigned, it's available to be used as a variable).
 
 For example, once the following line is processed,
 
@@ -196,9 +205,33 @@ base:
   font_size_small: $base_font_size * 0.85
 ----
 
-We'll cover more about math expressions in the next section.
+We'll cover more about math expressions later.
+
+==== Custom variables
+
+You can define arbitrary key names to make custom variables.
+This is one way to group reusable values at the top of your theme file.
+If you are going to do this, it's recommended that you organize the keys under a custom namespace, such as `brand`.
+
+For instance, here's how you can define your (very patriotic) brand colors:
+
+[source,yaml]
+----
+brand:
+  red: #E0162B
+  white: #FFFFFF
+  blue: #0052A5
+----
+
+You can now use these custom variables later in the theme file:
+
+[source,yaml]
+----
+base:
+  font_color: $brand_blue
+----
 
-=== Math Expressions & Functions
+=== Math expressions & functions
 
 The theme language supports basic math operations to support calculated values.
 The following table lists the supported operations and the corresponding operator for each.
@@ -261,7 +294,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.
@@ -295,11 +328,20 @@ page:
   margin: [0.75in, 1in, 0.75in, 1in]
 ----
 
+The order of elements in a measurement array is the same as it is in CSS:
+
+. top
+. right
+. bottom
+. left
+
 === Colors
 
 The theme language supports color values in three formats:
 
 Hex:: A string of 3 or 6 characters with an optional leading `#`.
++
+The special value `transparent` indicates that a color should not be used.
 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%.
 
@@ -330,6 +372,14 @@ base:
   font_color: #ff0000
 ----
 
+It's also possible to specify no color by assigning the special value `transparent` as shown here:
+
+[source,yaml]
+----
+base:
+  background_color: transparent
+----
+
 ==== RGB
 
 An RGB array value must be three numbers ranging from 0 to 255.
@@ -372,14 +422,47 @@ base:
 
 === Images
 
-PENDING
+An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
+Images are currently resolved relative to the value of the `pdf-stylesdir` attribute.
+
+The following image types (and corresponding file extensions) are supported:
+
+* PNG (.png)
+* JPEG (.jpg)
+* SVG (.svg)
+
+CAUTION: The GIF format (.gif) is not supported.
+
+Here's how an image is specified in the theme file as a bare image path:
+
+[source,yaml]
+----
+title_page:
+  background_image: title-cover.png
+----
+
+Here's how the image is specified using the inline image macro:
+
+[source,yaml]
+----
+title_page:
+  background_image: image:title-cover.png[]
+----
+
+Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment:
+
+[source,yaml]
+----
+title_page:
+  logo_image: image:logo.png[width=250,align=center] 
+----
 
 == Fonts
 
-You can select from built-in PDF fonts or custom fonts loaded from TrueType font (TTF) files.
+You can select from <<built-in-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 Fonts
+=== Built-in (AFM) fonts
 
 The names of the built-in fonts (for general-purpose text) are as follows:
 
@@ -407,15 +490,45 @@ base:
   font_family: Times-Roman
 ----
 
-However, when you use a built-in font, the characters that you use in your document are limited to the WINANSI (http://en.wikipedia.org/wiki/Windows-1252[Windows-1252]) code set.
+However, when you use a built-in font, the characters that you use in your document are limited to the characters in the WINANSI (http://en.wikipedia.org/wiki/Windows-1252[Windows-1252]) code set.
 WINANSI includes most of the characters needed for writing in Western languages (English, French, Spanish, etc).
 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.
-Any characters in your AsciiDoc document that cannot be encoded will be replaced with an underscore (`_`).
 
-=== Custom Fonts
+.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.
+
+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
+
+Asciidoctor PDF bundles several fonts that are used in the default theme.
+You can also use these fonts in your custom theme.
+These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8.
+
+The family name of the fonts bundled with Asciidoctor PDF are as follows:
+
+http://www.google.com/get/noto/#/family/noto-serif[Noto Serif]::
+A serif font that can be styled as normal, italic, bold or bold_italic.
+
+http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1mn[M+ 1mn]::
+A monospaced font that maps different thicknesses to the styles normal, italic, bold and bold_italic.
+Also provides the circuled numbers used in callouts.
+
+http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p[M+ 1p Fallback]::
+A sans-serif font that provides a very complete set of Unicode glyphs.
+Cannot be styled as italic, bold or bold_italic.
+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
 
 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.
@@ -482,13 +595,17 @@ font:
       italic: roboto-italic.ttf
       bold: roboto-bold.ttf
       bold_italic: roboto-bold_italic.ttf
-    RobotoLight:
+    Roboto Light:
       normal: roboto-light-normal.ttf
       italic: roboto-light-italic.ttf
       bold: roboto-light-bold.ttf
       bold_italic: roboto-light-bold_italic.ttf
 ----
 
+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
 
 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.
@@ -549,16 +666,21 @@ TBW
 
 === Page
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |page_background_color
 |<<colors,color>>
-|background_color: ffffff
+|background_color: #ffffff
+
+|page_background_image
+|path (relative to pdf-stylesdir)
+|background_image: watermark.jpg
 
 |page_layout
-|portrait, landscape
+|portrait, landscape +
+(default: portrait)
 |layout: portrait
 
 |page_margin
@@ -566,13 +688,13 @@ TBW
 |margin: [0.5in, 0.67in, 0.67in, 0.67in]
 
 |page_size
-|named size, <<measurement-units,measurement array [2]>>
+|named size, <<measurement-units,measurement array [width, height]>>
 |size: Letter
 |===
 
 === Base
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -582,17 +704,17 @@ TBW
 
 |base_font_family
 |<<fonts,font family name>>
-|font_family: NotoSerif
+|font_family: Noto Serif
 
 |base_font_size
 |<<values,number>>
 |font_size: 10.5
 
-|base_line_height_length
+|base_line_height_length^[1]^
 |<<values,number>>
 |line_height_length: 12
 
-|base_line_height
+|base_line_height^[1]^
 |<<values,number>>
 |line_height: 1.14
 
@@ -622,12 +744,15 @@ TBW
 
 |base_border_color
 |<<colors,color>>
-|border_color: eee
+|border_color: #eeeeee
 |===
 
-=== Vertical and Horizontal Rhythm
+^[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.
 
-[cols="1d,1d,2m"]
+=== Vertical and horizontal rhythm
+
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -640,15 +765,18 @@ TBW
 |horizontal_rhythm: 12
 |===
 
+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="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |link_font_color
 |<<colors,color>>
-|font_color: 428BCA
+|font_color: #428bca
 
 |link_font_family
 |<<fonts,font family name>>
@@ -663,21 +791,21 @@ TBW
 |font_style: normal
 |===
 
-=== Literal Inline
+=== Literal inline
 
 The literal key is used for inline monospaced text in prose and table cells.
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |literal_font_color
 |<<colors,color>>
-|font_color: B12146
+|font_color: #b12146
 
 |literal_font_family
 |<<fonts,font family name>>
-|font_family: Mplus1mn
+|font_family: M+ 1mn
 
 |literal_font_size
 |<<values,number>>
@@ -690,39 +818,39 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Heading
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |heading_font_color
 |<<colors,color>>
-|font_color: 333333
-
-|heading_h<n>_font_color
-|<<colors,color>>
-|h2_font_color: [0, 99%, 100%, 0]
+|font_color: #333333
 
 |heading_font_family
 |<<fonts,font family name>>
-|font_family: NotoSerif
-
-|heading_h<n>_font_family
-|<<fonts,font family name>>
-|h4_font_family: Roboto
+|font_family: Noto Serif
 
 |heading_font_size
 |<<values,number>>
 |font_size: 9
 
-|heading_h<n>_font_size
-|<<values,number>>
-|h6_font_size: round($base_font_size * 1.7)
-
 |heading_font_style
 |normal, italic, bold, bold_italic
 |font_style: bold
 
-|heading_h<n>_font_style
+|heading_h<n>_font_color^[1]^
+|<<colors,color>>
+|h2_font_color: [0, 99%, 100%, 0]
+
+|heading_h<n>_font_family^[1]^
+|<<fonts,font family name>>
+|h4_font_family: Roboto
+
+|heading_h<n>_font_size^[1]^
+|<<values,number>>
+|h6_font_size: round($base_font_size * 1.7)
+
+|heading_h<n>_font_style^[1]^
 |normal, italic, bold, bold_italic
 |h3_font_style: bold_italic
 
@@ -739,9 +867,11 @@ The literal key is used for inline monospaced text in prose and table cells.
 |margin_bottom: 9.600
 |===
 
-=== Title Page
+^[1]^ `<n>` may be a number ranging from 1 to 6, representing each of the six heading levels.
 
-[cols="1d,1d,2m"]
+=== Title page
+
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -749,6 +879,18 @@ The literal key is used for inline monospaced text in prose and table cells.
 |left, center, right, justify
 |align: right
 
+|title_page_logo_align
+|left, center, right
+|logo_align: right
+
+|title_page_logo_image
+|inline image macro
+|+logo_image: image:logo.png[scaledwidth=25%]+
+
+|title_page_logo_top
+|percentage
+|logo_top: 25%
+
 |title_page_title_top
 |percentage
 |title_top: 55%
@@ -759,7 +901,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |title_page_title_font_color
 |<<colors,color>>
-|title_font_color: 999999
+|title_font_color: #999999
 
 |title_page_title_line_height
 |<<values,number>>
@@ -787,7 +929,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |title_page_authors_font_color
 |<<colors,color>>
-|authors_font_color: 181818
+|authors_font_color: #181818
 
 |title_page_revision_margin_top
 |<<measurement-units,measurement>>
@@ -796,9 +938,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Block
 
-// Blocks include admonition, example, quote, verse, sidebar, image, listing, literal, and table.
-
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -815,19 +955,37 @@ The literal key is used for inline monospaced text in prose and table cells.
 |margin_bottom: 1
 |===
 
+Block styles are applied to the following block types:
+
+[cols="1a,1a,1a", grid=none, frame=none]
+|===
+|
+* admonition
+* example
+* quote
+|
+* verse
+* sidebar
+* image
+|
+* listing
+* literal
+* table
+|===
+
 === Caption
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |caption_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |caption_font_family
 |<<fonts,font family name>>
-|font_family: Mplus1mn
+|font_family: M+ 1mn
 
 |caption_font_size
 |<<values,number>>
@@ -852,17 +1010,17 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Code
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |code_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |code_font_family
 |<<fonts,font family name>>
-|font_family: Mplus1mn
+|font_family: M+ 1mn
 
 |code_font_size
 |<<values,number>>
@@ -882,11 +1040,11 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |code_background_color
 |<<colors,color>>
-|background_color: F5F5F5
+|background_color: #f5f5f5
 
 |code_border_color
 |<<colors,color>>
-|border_color: CCCCCC
+|border_color: #cccccc
 
 |code_border_radius
 |<<values,number>>
@@ -899,17 +1057,17 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Blockquote
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |blockquote_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |blockquote_font_family
 |<<fonts,font family name>>
-|font_family: Notoserif
+|font_family: Noto Serif
 
 |blockquote_font_size
 |<<values,number>>
@@ -925,7 +1083,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |blockquote_border_color
 |<<colors,color>>
-|border_color: EEEEEE
+|border_color: #eeeeee
 
 |blockquote_cite_font_size
 |<<values,number>>
@@ -933,11 +1091,11 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |blockquote_cite_font_color
 |<<colors,color>>
-|cite_font_color: 999999
+|cite_font_color: #999999
 
 |blockquote_cite_font_family
 |<<fonts,font family name>>
-|cite_font_family: Notoserif
+|cite_font_family: Noto Serif
 
 |blockquote_cite_font_style
 |normal, italic, bold, bold_italic
@@ -947,13 +1105,13 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Sidebar
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |sidebar_border_color
 |<<colors,color>>
-|border_color: FFFFFF
+|border_color: #ffffff
 
 |sidebar_border_radius
 |<<values,number>>
@@ -965,15 +1123,15 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |sidebar_background_color
 |<<colors,color>>
-|background_color: EEEEEE
+|background_color: #eeeeee
 
 |sidebar_title_font_color
 |<<colors,color>>
-|title_font_color: 333333
+|title_font_color: #333333
 
 |sidebar_title_font_family
 |<<fonts,font family name>>
-|title_font_family: NotoSerif
+|title_font_family: Noto Serif
 
 |sidebar_title_font_size
 |<<values,number>>
@@ -990,13 +1148,13 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Example
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |example_border_color
 |<<colors,color>>
-|border_color: EEEEEE
+|border_color: #eeeeee
 
 |example_border_radius
 |<<values,number>>
@@ -1008,18 +1166,18 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |example_background_color
 |<<colors,color>>
-|background_color: transparent
+|background_color: #fffef7
 |===
 
 === Admonition
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |admonition_border_color
 |<<colors,color>>
-|border_color: EEEEEE
+|border_color: #eeeeee
 
 |admonition_border_width
 |<<values,number>>
@@ -1028,7 +1186,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Image
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -1039,7 +1197,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Lead
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -1054,13 +1212,13 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Abstract
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |abstract_font_color
 |<<colors,color>>
-|font_color: 5C6266
+|font_color: #5c6266
 
 |abstract_font_size
 |<<values,number>>
@@ -1075,15 +1233,24 @@ The literal key is used for inline monospaced text in prose and table cells.
 |font_style: italic
 |===
 
-=== Thematic Break
+=== Thematic break
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |thematic_break_border_color
 |<<colors,color>>
-|border_colorL EEEEEE
+|border_color: #eeeeee
+
+|thematic_break_border_style
+|solid, double, dashed, dotted +
+(default: solid)
+|border_style: dashed
+
+|thematic_break_border_width
+|<<measurement-units,measurement>>
+|border_width: 0.5
 
 |thematic_break_margin_top
 |<<measurement-units,measurement>>
@@ -1096,7 +1263,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Description list
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -1112,7 +1279,7 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Outline list
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -1127,25 +1294,25 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 === Table
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |table_background_color
 |<<colors,color>>
-|background_color: FFFFFF
+|background_color: #ffffff
 
 |table_even_row_background_color
 |<<colors,color>>
-|even_row_background_color: F9F9F9
+|even_row_background_color: #f9f9f9
 
 |table_foot_background_color
 |<<colors,color>>
-|foot_background_color: F0F0F0
+|foot_background_color: #f0f0f0
 
 |table_border_color
 |<<colors,color>>
-|border_color: DDDDDD
+|border_color: #dddddd
 
 |table_border_width
 |<<values,number>>
@@ -1157,9 +1324,9 @@ The literal key is used for inline monospaced text in prose and table cells.
 |===
 
 [[key-toc]]
-=== Table of Contents
+=== Table of contents
 
-[cols="1d,1d,2m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
@@ -1169,19 +1336,19 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |toc_dot_leader_color
 |<<colors,color>>
-|dot_leader_color: 999999
+|dot_leader_color: #999999
 
 |toc_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |toc_h<n>_font_color
 |<<colors,color>>
-|h3_font_color: 999999
+|h3_font_color: #999999
 
 |toc_font_family
 |<<fonts,font family name>>
-|font_family: NotoSerif
+|font_family: Noto Serif
 
 |toc_font_size
 |<<values,number>>
@@ -1204,19 +1371,24 @@ The literal key is used for inline monospaced text in prose and table cells.
 |indent: 20
 |===
 
-=== Running Header & Footer
+=== Running header & footer
 
-[cols="3,5,5m"]
+[cols="3,3,5m"]
 |===
 |Key |Value Type |Example
 
 |header_background_color
 |<<colors,color>>
-|background_color: EEEEEE
+|background_color: #eeeeee
 
 |header_border_color
 |<<colors,color>>
-|border_color: DDDDDD
+|border_color: #dddddd
+
+|header_border_style
+|solid, double, dashed, dotted +
+(default: solid)
+|border_style: dashed
 
 |header_border_width
 |<<measurement-units,measurement>>
@@ -1224,11 +1396,11 @@ The literal key is used for inline monospaced text in prose and table cells.
 
 |header_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |header_font_family
 |<<fonts,font family name>>
-|font_family: NotoSerif
+|font_family: Noto Serif
 
 |header_font_size
 |<<values,number>>
@@ -1254,18 +1426,22 @@ The literal key is used for inline monospaced text in prose and table cells.
 |top, center, bottom
 |valign: center
 
-|header_<side>_content_<align>*
+|header_<side>_content_<align>^[1]^
 |quoted string
-v|`recto_content:
-  right: '\{page-number}'`
+|right: '\{page-number}'
 
 |footer_background_color
 |<<colors,color>>
-|background_color: EEEEEE
+|background_color: #eeeeee
 
 |footer_border_color
 |<<colors,color>>
-|border_color: DDDDDD
+|border_color: #dddddd
+
+|footer_border_style
+|solid, double, dashed, dotted +
+(default: solid)
+|border_style: dashed
 
 |footer_border_width
 |<<measurement-units,measurement>>
@@ -1273,11 +1449,11 @@ v|`recto_content:
 
 |footer_font_color
 |<<colors,color>>
-|font_color: 333333
+|font_color: #333333
 
 |footer_font_family
 |<<fonts,font family name>>
-|font_family: NotoSerif
+|font_family: Noto Serif
 
 |footer_font_size
 |<<values,number>>
@@ -1303,13 +1479,12 @@ v|`recto_content:
 |top, center, bottom
 |valign: top
 
-|footer_<side>_content_<align>*
+|footer_<side>_content_<align>^[1]^
 |quoted string
-v|`recto_content:
-  center: '\{page-number}'`
+|center: '\{page-number}'
 |===
 
-{asterisk} `<side>` can be `recto` (odd pages) or `verso` (even pages).
+^[1]^ `<side>` can be `recto` (odd pages) or `verso` (even pages).
 `<align>` 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.
@@ -1317,6 +1492,8 @@ IMPORTANT: You must define a height for the running header or footer, respective
 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.
 
+==== Implicit attributes
+
 In addition to the document-level attributes defined in the AsciiDoc document, the following attributes are available when defining the content keys in the footer:
 
 * page-count
@@ -1327,18 +1504,95 @@ In addition to the document-level attributes defined in the AsciiDoc document, t
 * section-title
 * section-or-chapter-title
 
-For example:
+Here's an example that shows how these attributes can be used in the running footer:
 
 [source,yaml]
 ----
 footer:
   height: 0.75in
   recto_content:
-    right: '{section-or-chapter-title} | {page-number}'
+    right: '{section-or-chapter-title} | *{page-number}*'
+  verso_content:
+    left: '*{page-number}* | {chapter-title}'
+----
+
+TIP: You can use most AsciiDoc inline formatting in the values of these keys.
+For instance, to make the text bold, surround it in asterisks (as shown above).
+One exception to this rule are inline images, which are described in the next section.
+
+==== Images
+
+You can add an image to the running header or footer using the AsciiDoc inline image syntax.
+Note that the image must be the whole value for a given position (left, center or right).
+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]
+----
+header:
+  height: 0.75in
+  image_valign: 2 # <1>
+  recto_content:
+    center: image:footer-logo.png[width=80]
   verso_content:
-    left: '{page-number} | {chapter-title}'
+    center: $header_recto_content_center
 ----
+<1> You can use the `footer_valign` attribute to slighly nudge the image up or down.
+
+CAUTION: 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.
+
+== Applying your theme
+
+After creating a theme, you'll need to tell Asciidoctor PDF where to find it.
+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.
+_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`).
+
+pdf-fontsdir:: The directory where the fonts used by your theme, if any, are located.
+_Specifying an absolute path is recommended._
+
+Let's assume that you've put your theme files inside a directory named `resources` with the following layout:
+
+....
+document.adoc
+resources/
+  themes/
+    basic-theme.yml
+  fonts/
+    roboto-normal.ttf
+    roboto-italic.ttf
+    roboto-bold.ttf
+    roboto-bold_italic.ttf
+....
+
+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
+
+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.
+
+ $ asciidoctor-pdf -a pdf-style=resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts
+
+However, in this case, image paths in your theme won't be resolved properly.
 
-== Applying a Theme
+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.
 
-PENDING
+  $ asciidoctor-pdf -a pdf-stylesdir=/path/to/resources/themes -a pdf-style=basic -a pdf-fontsdir=/path/to/resources/fonts