add text value definitions (PR #2109)

34 files changed, 341 insertions, 244 deletions

diff --git a/docs/modules/theme/pages/abstract.adoc b/docs/modules/theme/pages/abstract.adoc
index ad7c0696..e4d17128 100644
--- a/docs/modules/theme/pages/abstract.adoc
+++ b/docs/modules/theme/pages/abstract.adoc
@@ -16,7 +16,7 @@ The keys in the `abstract` category control the arrangement and style of the abs
 (default: `$base-font-color`)
 |[source]
 abstract:
-  font-color: '#5c6266'
+  font-color: #5c6266
 
 |font-size
 |xref:language.adoc#values[Number] +
@@ -46,9 +46,30 @@ abstract:
 abstract:
   padding: [0, 12, 0, 12]
 
+|text-decoration
+|xref:text.adoc#decoration[Text decoration] +
+(default: `none`)
+|[source]
+abstract:
+  text-decoration: underline
+
+|text-decoration-color
+|xref:color.adoc[Color] +
+(default: `$abstract-font-color`)
+|[source]
+abstract:
+  text-decoration-color: #0000ff
+
+|text-decoration-width
+|xref:measurement-units.adoc[Measurement] +
+(default: `$base-text-decoration-width`)
+|[source]
+abstract:
+  text-decoration-width: 0.5
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
-(default: `$base-text-transform`)
+(default: _inherit_)
 |[source]
 abstract:
   text-transform: uppercase
@@ -69,7 +90,7 @@ The keys in the `abstract-first-line` category control the style of the first li
 |[source]
 abstract:
   first-line:
-    font-color: '#AA0000'
+    font-color: #AA0000
 
 |font-style
 |xref:text.adoc#font-style[Font style] +
@@ -89,21 +110,13 @@ The keys in the `abstract-title` category control the style and alignment of the
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `center`)
-|[source]
-abstract:
-  title:
-    text-align: center
-
 |font-color
 |xref:color.adoc[Color] +
 (default: `$base-font-color`)
 |[source]
 abstract:
   title:
-    font-color: '#333333'
+    font-color: #333333
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -135,13 +148,45 @@ abstract:
 |[source]
 abstract:
   title:
-    font-style: bold
+    font-style: normal_italic
+
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `center`)
+|[source]
+abstract:
+  title:
+    text-align: center
+
+|text-decoration
+|xref:text.adoc#decoration[Text decoration] +
+(default: `none`)
+|[source]
+abstract:
+  title:
+    text-decoration: underline
+
+|text-decoration-color
+|xref:color.adoc[Color] +
+(default: `$abstract-title-font-color`)
+|[source]
+abstract:
+  title:
+    text-decoration-color: #0000ff
+
+|text-decoration-width
+|xref:measurement-units.adoc[Measurement] +
+(default: `$base-text-decoration-width`)
+|[source]
+abstract:
+  title:
+    text-decoration-width: 0.5
 
 |text-transform
 |xref:text.adoc#transform[Text transform] +
-(default: `$base-text-transform`)
+(default: _inherit_)
 |[source]
 abstract:
   title:
-    text-transform: uppercase
+    text-transform: captitalize
 |===
diff --git a/docs/modules/theme/pages/admonition.adoc b/docs/modules/theme/pages/admonition.adoc
index cab0587e..7fe10914 100644
--- a/docs/modules/theme/pages/admonition.adoc
+++ b/docs/modules/theme/pages/admonition.adoc
@@ -33,7 +33,7 @@ admonition:
   border-radius: 4
 
 |border-style
-|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid`  {vbar} +
+|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
 (default: `solid`)
 |[source]
 admonition:
@@ -56,7 +56,7 @@ admonition:
   column-rule-color: #aa0000
 
 |column-rule-style
-|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid`  {vbar} +
+|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
 (default: `solid`)
 |[source]
 admonition:
@@ -128,14 +128,6 @@ The keys in the `admonition-label` category control the arrangement and style of
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `center`)
-|[source]
-admonition:
-  label:
-    text-align: left
-
 |font-color
 |xref:color.adoc[Color] +
 (default: _inherit_)
@@ -192,6 +184,14 @@ admonition:
   label:
     padding: [0, 12, 0, 12]
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `center`)
+|[source]
+admonition:
+  label:
+    text-align: left
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: `uppercase`)
diff --git a/docs/modules/theme/pages/base.adoc b/docs/modules/theme/pages/base.adoc
index c3c0006d..c747e458 100644
--- a/docs/modules/theme/pages/base.adoc
+++ b/docs/modules/theme/pages/base.adoc
@@ -14,13 +14,6 @@ TIP: While it's common to define additional keys in this category (e.g., `base-b
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `left`)
-|[source]
-base:
-  text-align: justify
-
 |border-color
 |xref:color.adoc[Color] +
 (default: `'EEEEEE'`)
@@ -93,6 +86,27 @@ base:
 base:
   line-height-length: 12
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `left`)
+|[source]
+base:
+  text-align: center
+
+|text-decoration
+|xref:text.adoc#decoration[Text decoration] +
+(default: `none`)
+|[source]
+base:
+  text-decoration: underline
+
+|text-decoration-color
+|xref:color.adoc[Color] +
+(default: `$base-font-color`)
+|[source]
+base:
+  text-decoration-color: #0000ff
+
 |text-decoration-width
 |xref:measurement-units.adoc[Measurement] +
 (default: `1`)
@@ -101,11 +115,8 @@ base:
   text-decoration-width: 0.5
 
 |<<transform,text-transform>>
-|`none` +
-(default: `none`)
-|[source]
-base:
-  text-transform: none
+|Implicitly set to `none` on `base`.
+|_Can't be set on base_.
 |===
 
 [#height]
@@ -120,6 +131,6 @@ You don't have to go about it this way in your own theme.
 == text-transform
 
 The `text-transform` key can't be set globally.
-Therefore, this key shouldn't be used.
+Therefore, this key shouldn't be used on the `base` category.
 The value of `none` is implicit and is only documented in the table above for completeness.
 
diff --git a/docs/modules/theme/pages/block-image.adoc b/docs/modules/theme/pages/block-image.adoc
index 0c50e879..843a70c2 100644
--- a/docs/modules/theme/pages/block-image.adoc
+++ b/docs/modules/theme/pages/block-image.adoc
@@ -12,7 +12,7 @@ The keys in the `image` category control the arrangement and style of block imag
 |Key |Value Type |Example
 
 |align
-|xref:image.adoc#align[Image alignment] +
+|xref:blocks.adoc#align[Block alignment] +
 (default: `left`)
 |[source]
 image:
@@ -40,7 +40,7 @@ image:
   border-radius: 2
 
 |border-style
-|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid`
+|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
 (default: `solid`)
 |[source]
 image:
@@ -153,7 +153,7 @@ The keys in the `image-caption` category control the arrangement and style of th
 |Key |Value Type |Example
 
 |caption-align
-|xref:block.adoc#align[Alignment] {vbar} inherit +
+|xref:block.adoc#align[Block alignment] {vbar} inherit +
 (default: `$caption-align`)
 |[source]
 image:
diff --git a/docs/modules/theme/pages/blocks.adoc b/docs/modules/theme/pages/blocks.adoc
index 4e5c9a4f..f0a45034 100644
--- a/docs/modules/theme/pages/blocks.adoc
+++ b/docs/modules/theme/pages/blocks.adoc
@@ -1,7 +1,7 @@
 = Block Styles
 
 [#align]
-== Alignment
+== Block alignment
 
 The `align` key is used to align a block element horizontally within its parent container.
 This key is used for non-text elements, such as an image, table, or caption with a narrower width than the content area.
@@ -9,9 +9,9 @@ It's roughly akin to the function of the `align-self` property of a flexbox elem
 
 The element can be aligned using the following keywords:
 
-* `left`
-* `center`
-* `right`
+`center`:: The block is centered horizontally within the parent container.
+`left`:: The block is aligned to the left side of the parent container.
+`right`:: The block is aligned to the right side of the parent container.
 
 The `align` key is distinct from the similarly-named `text-align` key.
-The latter key aligns text within the container (i.e., the text box) using text alignment rules.
+The xref:text.adoc#text-align[text-align key] aligns text within the text box using text alignment rules.
diff --git a/docs/modules/theme/pages/button.adoc b/docs/modules/theme/pages/button.adoc
index b72c87a1..18c727fd 100644
--- a/docs/modules/theme/pages/button.adoc
+++ b/docs/modules/theme/pages/button.adoc
@@ -27,7 +27,7 @@ button:
 
 |<<border-offset,border-offset>>
 |xref:language.adoc#values[Number] +
-(default: 0)
+(default: `0`)
 |[source]
 button:
   border-offset: 1.5
diff --git a/docs/modules/theme/pages/callout.adoc b/docs/modules/theme/pages/callout.adoc
index c59841d8..4bfa292d 100644
--- a/docs/modules/theme/pages/callout.adoc
+++ b/docs/modules/theme/pages/callout.adoc
@@ -19,7 +19,7 @@ Also see <<inherit>> for more information.
 (default: _inherit_)
 |[source]
 callout-list:
-  font-color: '#555555'
+  font-color: #555555
 
 |<<inherit,font-family>>
 |xref:font-support.adoc[Font family name] +
@@ -65,7 +65,7 @@ callout-list:
 
 |margin-top-after-code
 |xref:measurement-units.adoc[Measurement] +
-(default: `-$block-margin-bottom`)
+(default: `-6`)
 |[source]
 callout-list:
   margin-top-after-code: 0
diff --git a/docs/modules/theme/pages/caption.adoc b/docs/modules/theme/pages/caption.adoc
index c8077d1a..709f9deb 100644
--- a/docs/modules/theme/pages/caption.adoc
+++ b/docs/modules/theme/pages/caption.adoc
@@ -13,7 +13,7 @@ The value `inherit` resolves to the alignment of the block image.
 |Key |Value Type |Example
 
 |align
-|xref:blocks.adoc#align[Alignment] +
+|xref:blocks.adoc#align[Block alignment] +
 (default: `left`)
 |[source]
 caption:
@@ -24,14 +24,14 @@ caption:
 (default: _not set_)
 |[source]
 caption:
-  background-color: '#DDDDDD'
+  background-color: #DDDDDD
 
 |font-color
 |xref:color.adoc[Color] +
 (default: _inherit_)
 |[source]
 caption:
-  font-color: '#333333'
+  font-color: #333333
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -41,7 +41,7 @@ caption:
   font-family: M+ 1mn
 
 |font-kerning
-|normal {vbar} none +
+|`normal` {vbar} `none` +
 (default: _inherit_)
 |[source]
 caption:
@@ -61,8 +61,22 @@ caption:
 caption:
   font-style: italic
 
+|margin-inside
+|xref:measurement-units.adoc[Measurement] +
+(default: `4`)
+|[source]
+caption:
+  margin-inside: 3
+
+|margin-outside
+|xref:measurement-units.adoc[Measurement] +
+(default: `0`)
+|[source]
+caption:
+  margin-outside: 0
+
 |text-align
-|xref:text.adoc#text-align[Text Alignment] +
+|xref:text.adoc#text-align[Text alignment] +
 (default: `$<category>-caption-align` or `$caption-align`)
 |[source]
 caption:
@@ -80,7 +94,7 @@ caption:
 (default: `$caption-font-color`)
 |[source]
 caption:
-  text-decoration-color: '#ff0000'
+  text-decoration-color: #ff0000
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -95,18 +109,4 @@ caption:
 |[source]
 caption:
   text-transform: uppercase
-
-|margin-inside
-|xref:measurement-units.adoc[Measurement] +
-(default: `4`)
-|[source]
-caption:
-  margin-inside: 3
-
-|margin-outside
-|xref:measurement-units.adoc[Measurement] +
-(default: `0`)
-|[source]
-caption:
-  margin-outside: 0
 |===
diff --git a/docs/modules/theme/pages/code.adoc b/docs/modules/theme/pages/code.adoc
index 21bc09c6..3b04f119 100644
--- a/docs/modules/theme/pages/code.adoc
+++ b/docs/modules/theme/pages/code.adoc
@@ -33,7 +33,7 @@ code:
   border-radius: 4
 
 |border-style
-|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid`
+|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
 (default: `solid`)
 |[source]
 code:
diff --git a/docs/modules/theme/pages/color.adoc b/docs/modules/theme/pages/color.adoc
index 121e46c1..2ba2094b 100644
--- a/docs/modules/theme/pages/color.adoc
+++ b/docs/modules/theme/pages/color.adoc
@@ -38,10 +38,10 @@ The following are all equivalent values for the color red:
 
 Here's how a hex color value appears in the theme file:
 
-[source,yaml]
+[,yaml]
 ----
 base:
-  font-color: '#ff0000'
+  font-color: #ff0000
 ----
 
 == RGB
@@ -57,7 +57,7 @@ Here's how to specify the color red in RGB:
 
 Here's how a RGB color value appears in the theme file:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-color: [255, 0, 0]
@@ -78,7 +78,7 @@ Here's how to specify the color red in CMYK:
 
 Here's how a CMYK color value appears in the theme file:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-color: [0, 0.99, 1, 0]
@@ -88,7 +88,7 @@ base:
 
 It's possible to specify no color by assigning the special value `transparent`, as shown here:
 
-[source,yaml]
+[,yaml]
 ----
 table:
   background-color: transparent
diff --git a/docs/modules/theme/pages/description-list.adoc b/docs/modules/theme/pages/description-list.adoc
index f70802bc..a7f24ff5 100644
--- a/docs/modules/theme/pages/description-list.adoc
+++ b/docs/modules/theme/pages/description-list.adoc
@@ -23,7 +23,7 @@ description-list:
 (default: _inherit_)
 |[source]
 description-list:
-  term-font-color: '#AA0000'
+  term-font-color: #AA0000
 
 |term-font-family
 |xref:font-support.adoc[Font family name] +
@@ -33,7 +33,7 @@ description-list:
   term-font-family: Noto Serif
 
 |term-font-kerning
-|normal {vbar} none +
+|`normal` {vbar} `none` +
 (default: _inherit_)
 |[source]
 description-list:
diff --git a/docs/modules/theme/pages/extend-theme.adoc b/docs/modules/theme/pages/extend-theme.adoc
index 69d4a471..d94f19e7 100644
--- a/docs/modules/theme/pages/extend-theme.adoc
+++ b/docs/modules/theme/pages/extend-theme.adoc
@@ -1,4 +1,5 @@
 = Customize the Theme
+:description: Customize a PDF theme by extending a built-in theme.
 
 [#extend-default]
 == Extend the default theme
@@ -6,11 +7,11 @@
 A theme can extend another theme using the `extends` key.
 For example:
 
-[source,yaml]
+[,yaml]
 ----
 extends: default
 base:
-  font-color: '#ff0000'
+  font-color: #ff0000
 ----
 
 The `extends` key accepts either a single value or an array of values.
@@ -21,7 +22,7 @@ If the filename begins with `./`, it's resolved as a theme file relative to the
 Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).
 
 Currently, the theme starts out empty.
-Then, the files referenced by the extends key are loaded in order.
+Then, the files referenced by the `extends` key are loaded in order.
 Finally, the keys in the current file are loaded.
 Each time a theme is loaded, the keys are overlaid onto the keys from the previous theme.
 
@@ -30,7 +31,7 @@ Each time a theme is loaded, the keys are overlaid onto the keys from the previo
 Here's an example of a basic theme file that extends the base theme:
 
 .basic-theme.yml
-[source,yaml]
+[,yaml]
 ----
 extends: base
 page:
@@ -38,21 +39,25 @@ page:
   margin: [0.75in, 1in, 0.75in, 1in]
   size: Letter
 base:
-  font-color: '#333333'
+  font-color: #333333
   font-family: Times-Roman
   font-size: 12
   line-height-length: 17
   line-height: $base-line-height-length / $base-font-size
-vertical-spacing: $base-line-height-length
+role:
+  removed:
+    font-style: italic
+    text-decoration: line-through
+    text-decoration-color: #ff0000
 heading:
-  font-color: '#262626'
+  font-color: #262626
   font-size: 17
   font-style: bold
   line-height: 1.2
-  margin-bottom: $vertical-spacing
+  margin-bottom: 10
 link:
-  font-color: '#002FA7'
-outline-list:
+  font-color: #002FA7
+list:
   indent: $base-font-size * 1.5
 footer:
   height: $base-line-height-length * 2.5
@@ -72,16 +77,17 @@ The converter uses the information from the theme map to help construct the PDF.
 
 Instead of designing a theme from scratch, you can extend the default theme using the `extends` key as follows:
 
-[source,yaml]
+[,yaml]
 ----
 extends: default
 base:
-  font-color: '#ff0000'
+  font-color: #ff0000
 ----
 
-You can also point the extends key at another custom theme to extend from it.
+You can also point the `extends` key at another custom theme to extend from it.
 If you don't want to extend any theme, including the base theme, omit the `extends` key or assign the value `~` to the `extends` key (i.e., `extends: ~`).
 
+[#load-theme-more-than-once]
 If the same theme appears multiple times in the theme hierarchy, it will only be loaded once by default.
 You can force the theme to be loaded, even if it has already been loaded, by adding the `!important` keyword at the end of the value offset by a space.
 
diff --git a/docs/modules/theme/pages/font-support.adoc b/docs/modules/theme/pages/font-support.adoc
index de575996..07b60e9d 100644
--- a/docs/modules/theme/pages/font-support.adoc
+++ b/docs/modules/theme/pages/font-support.adoc
@@ -39,7 +39,7 @@ Using a built-in font requires no additional files.
 You can use the key anywhere a `font-family` property is accepted in the theme file.
 For example:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-family: Times-Roman
diff --git a/docs/modules/theme/pages/footnotes.adoc b/docs/modules/theme/pages/footnotes.adoc
index 220b5150..239e8d2c 100644
--- a/docs/modules/theme/pages/footnotes.adoc
+++ b/docs/modules/theme/pages/footnotes.adoc
@@ -15,7 +15,7 @@ The styling of the links is controlled by the xref:link.adoc[global link styles]
 (default: `$base-font-color`)
 |[source]
 footnotes:
-  font-color: '#cccccc'
+  font-color: #cccccc
 
 |font-size
 |xref:language.adoc#values[Number] +
@@ -43,7 +43,7 @@ footnotes:
 (default: `0`)
 |[source]
 footnotes:
-  margin-top: 10
+  margin-top: 2
 
 |text-transform
 |xref:text.adoc#transform[Text transform] +
diff --git a/docs/modules/theme/pages/heading.adoc b/docs/modules/theme/pages/heading.adoc
index 1957f1cb..005d23e8 100644
--- a/docs/modules/theme/pages/heading.adoc
+++ b/docs/modules/theme/pages/heading.adoc
@@ -11,19 +11,12 @@ The keys in the `heading` category control the style of most headings, including
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `$base-text-align`)
-|[source]
-heading:
-  text-align: center
-
 |font-color
 |xref:color.adoc[Color] +
 (default: _inherit_)
 |[source]
 heading:
-  font-color: '#222222'
+  font-color: #222222
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -33,7 +26,7 @@ heading:
   font-family: Noto Serif
 
 |font-kerning
-|normal {vbar} none +
+|`normal` {vbar} `none` +
 (default: _inherit_)
 |[source]
 heading:
@@ -76,11 +69,18 @@ heading:
 
 |min-height-after
 |xref:measurement-units.adoc[Measurement] +
-(default: `$base-font-size * $base-line-height * 1.5`)
+(default: `20`)
 |[source]
 heading:
   min-height-after: 0.5in
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$base-text-align`)
+|[source]
+heading:
+  text-align: center
+
 |text-decoration
 |xref:text.adoc#decoration[Text decoration] +
 (default: `none`)
@@ -93,7 +93,7 @@ heading:
 (default: `$heading-font-color`)
 |[source]
 heading:
-  text-decoration-color: '#cccccc'
+  text-decoration-color: #cccccc
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -123,13 +123,6 @@ the properties of chapter titles.
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `$heading-text-align`)
-|[source]
-heading:
-  h2-text-align: center
-
 |font-color
 |xref:color.adoc[Color] +
 (default: `$heading-font-color`)
@@ -153,7 +146,7 @@ heading:
 
 |<<font-size,font-size>>
 |xref:language.adoc#values[Number] +
-(default: <1>=`24`; <2>=`18`; <3>=`16`; <4>=`14`; <5>=`12`; <6>=`10`)
+(default: h1=`24`; h2=`18`; h3=`16`; h4=`14`; <h5=`12`; h6=`10`)
 |[source]
 heading:
   h6-font-size: $base-font-size * 1.7
@@ -186,6 +179,34 @@ heading:
 heading:
   h2-margin-top: 6
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$heading-text-align`)
+|[source]
+heading:
+  h2-text-align: center
+
+|text-decoration
+|xref:text.adoc#decoration[Text decoration] +
+(default: `$heading-text-decoration`)
+|[source]
+heading:
+  h4-text-decoration: underline
+
+|text-decoration-color
+|xref:color.adoc[Color] +
+(default: `$heading-text-decoration-color`)
+|[source]
+heading:
+  h4-text-decoration-color: #4c516d
+
+|text-decoration-width
+|xref:language.adoc#values[Number] +
+(default: `$heading-text-decoration-width`)
+|[source]
+heading:
+  h4-text-decoration-width: 0.2
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: `$heading-text-transform`)
diff --git a/docs/modules/theme/pages/image.adoc b/docs/modules/theme/pages/image.adoc
index c341b621..fdc25176 100644
--- a/docs/modules/theme/pages/image.adoc
+++ b/docs/modules/theme/pages/image.adoc
@@ -57,9 +57,5 @@ title-page:
   logo-image: image:logo.png[pdfwidth=2.5in,align=center]
 ----
 
-The `align` key is used to align images within the parent container.
-Images can be aligned as follows:
-
-* `left`
-* `center`
-* `right`
+The `align` setting is used to align block images within the parent container.
+See xref:blocks.adoc[] for accepted alignment keywords.
diff --git a/docs/modules/theme/pages/keys.adoc b/docs/modules/theme/pages/keys.adoc
index 41107a61..3331ea44 100644
--- a/docs/modules/theme/pages/keys.adoc
+++ b/docs/modules/theme/pages/keys.adoc
@@ -9,7 +9,7 @@ Each category represents a common prefix under which the keys are typically nest
 
 TIP: Keys can be nested wherever an underscore (`_`) or hyphen (`-`) appears in the name.
 This nested structure is for organizational purposes only.
-All keys are flatted when the theme is loaded (e.g., `align` nested under `base` becomes `base-align`).
+All keys are flatted when the theme is loaded (e.g., `text-align` nested under `base` becomes `base-text-align`).
 
 The converter uses the values of these keys to control how most elements are arranged and styled in the PDF.
 The default values listed in this section get inherited from the {url-repo-root}/data/themes/base-theme.yml[base theme^].
diff --git a/docs/modules/theme/pages/language.adoc b/docs/modules/theme/pages/language.adoc
index b2eb8163..dd608bb8 100644
--- a/docs/modules/theme/pages/language.adoc
+++ b/docs/modules/theme/pages/language.adoc
@@ -24,8 +24,12 @@ Some of these properties have different names from those found in CSS.
 
 * An underscore (`_`) may be used in place of a hyphen (`-`) in all property names (so you may use `font_family` or `font-family`).
 * An underscore (`_`) may be used in place of a hyphen (`-`) in all variable names (so you may use `$base_font_family` or `$base-font-family`).
-* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` property (allowed values: `normal`, `bold`, `italic`, and `bold_italic`).
-* The `align` property in the theme language is roughly equivalent to the `text-align` property in CSS.
+* Instead of separate properties for font weight and font style, the theme language combines these settings in the `font-style` key.
+See the xref:text.adoc#font-style[Font style section] for allowed values.
+* The `align` key in the theme language is roughly equivalent to the `align-self` flexbox property in CSS.
+See xref:blocks.adoc#align[Alignment for blocks] for more information.
+* The `text-align` key in the theme language has the same function as the `text-align` property in CSS.
+See xref:text.adoc#text-align[Text alignment] for more information.
 * The `font-color` property in the theme language is equivalent to the `color` property in CSS.
 
 [#values]
@@ -34,9 +38,9 @@ Some of these properties have different names from those found in CSS.
 The value of a key may be one of the following types:
 
 * String
-** Font family name (e.g., Roboto)
-** Font style (normal, bold, italic, bold_italic)
-** Alignment (left, center, right, justify)
+** Font family name
+** Font style
+** Alignment
 ** Color as hex string (e.g., 'ff0000', #ff0000, or '#ff0000')
 ** Image path
 ** Enumerated type (where specified)
@@ -71,7 +75,7 @@ This means the selector part (e.g., `link`) is combined with the property name (
 For example, let's assume we want to set the base (i.e., global) font size and color.
 These keys may be written longhand:
 
-[source,yaml]
+[,yaml]
 ----
 base-font-color: #333333
 base-font-family: Times-Roman
@@ -80,7 +84,7 @@ base-font-size: 12
 
 Or, to avoid having to type the prefix `base-` multiple times, the keys may be written as a hierarchy:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-color: #333333
@@ -90,7 +94,7 @@ base:
 
 Or even:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font:
diff --git a/docs/modules/theme/pages/link.adoc b/docs/modules/theme/pages/link.adoc
index cade300b..9a042226 100644
--- a/docs/modules/theme/pages/link.adoc
+++ b/docs/modules/theme/pages/link.adoc
@@ -13,7 +13,7 @@ The keys in the `link` category style hyperlink text.
 (default: _not set_)
 |[source]
 link:
-  background-color: '#efefef'
+  background-color: #efefef
 
 |border-offset
 |xref:language.adoc#values[Number] +
@@ -24,10 +24,10 @@ link:
 
 |font-color
 |xref:color.adoc[Color] +
-(default: `'#0000ee'`)
+(default: `'0000EE'`)
 |[source]
 link:
-  font-color: '#428bca'
+  font-color: #428bca
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -62,11 +62,11 @@ link:
 (default: `$link-font-color`)
 |[source]
 link:
-  text-decoration-color: '#0000ff'
+  text-decoration-color: #0000ff
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
-(default: `$base-text-decoration-width`)
+(default: _inherit_)
 |[source]
 link:
   text-decoration-width: 0.5
diff --git a/docs/modules/theme/pages/list.adoc b/docs/modules/theme/pages/list.adoc
index bc412a63..d182858d 100644
--- a/docs/modules/theme/pages/list.adoc
+++ b/docs/modules/theme/pages/list.adoc
@@ -30,14 +30,14 @@ list:
 (default: _inherit_)
 |[source]
 list:
-  marker-font-color: '#3c763d'
+  marker-font-color: #3c763d
 
 |text-align
 |xref:text.adoc#text-align[Text alignment] +
 (default: `$base-text-align`)
 |[source]
 list:
-  text-align: left
+  text-align: right
 |===
 
 The `marker-font-color` key controls the color of the bullet glyph that marks items in unordered lists and the color of the number or letter marker for items in ordered lists.
@@ -74,7 +74,7 @@ ulist:
 |[source]
 ulist:
   marker:
-    font-color: '#cccccc'
+    font-color: #cccccc
 
 |line-height
 |xref:language.adoc#values[Number] +
@@ -128,7 +128,7 @@ ulist:
 ulist:
   marker:
     disc:
-      font-color: '#ff0000'
+      font-color: #ff0000
 
 |line-height
 |xref:language.adoc#values[Number] +
diff --git a/docs/modules/theme/pages/mark.adoc b/docs/modules/theme/pages/mark.adoc
index edd25b63..5157113a 100644
--- a/docs/modules/theme/pages/mark.adoc
+++ b/docs/modules/theme/pages/mark.adoc
@@ -8,31 +8,31 @@ The keys in the `mark` category apply to an inline mark phrase.
 |===
 |Key |Value Type |Example
 
-|font-color
+|background-color
 |xref:color.adoc[Color] +
-(default: _inherit_)
+(default: `'FFFF00'`)
 |[source]
 mark:
-  font-color: '#333333'
+  background-color: #fcf8e3
 
-|font-style
-|xref:text.adoc#font-style[Font style] +
-(default: _inherit_)
+|border-offset
+|xref:language.adoc#values[Number] +
+(default: `1`)
 |[source]
 mark:
-  font-style: bold
+  border-offset: 2
 
-|background-color
+|font-color
 |xref:color.adoc[Color] +
-(default: `'#ff0000'`)
+(default: _inherit_)
 |[source]
 mark:
-  background-color: '#fcf8e3'
+  font-color: #333333
 
-|border-offset
-|xref:language.adoc#values[Number] +
-(default: `1`)
+|font-style
+|xref:text.adoc#font-style[Font style] +
+(default: _inherit_)
 |[source]
 mark:
-  border-offset: 2
+  font-style: bold
 |===
diff --git a/docs/modules/theme/pages/measurement-units.adoc b/docs/modules/theme/pages/measurement-units.adoc
index 70cf68bd..283fc57f 100644
--- a/docs/modules/theme/pages/measurement-units.adoc
+++ b/docs/modules/theme/pages/measurement-units.adoc
@@ -44,7 +44,7 @@ Currently, percentage units can only be used for placing elements on the title p
 
 Here's an example of how you can use inches to define the page margins:
 
-[source,yaml]
+[,yaml]
 ----
 page:
   margin: [0.75in, 1in, 0.75in, 1in]
diff --git a/docs/modules/theme/pages/menu.adoc b/docs/modules/theme/pages/menu.adoc
index 0db15bd7..1b2667a3 100644
--- a/docs/modules/theme/pages/menu.adoc
+++ b/docs/modules/theme/pages/menu.adoc
@@ -22,7 +22,7 @@ menu:
 (default: _inherit_)
 |[source]
 menu:
-  font-color: '#AA0000'
+  font-color: #AA0000
 
 |font-family
 |xref:font-support.adoc[Font family name] +
diff --git a/docs/modules/theme/pages/page.adoc b/docs/modules/theme/pages/page.adoc
index 7cc4ae1a..7397d773 100644
--- a/docs/modules/theme/pages/page.adoc
+++ b/docs/modules/theme/pages/page.adoc
@@ -17,10 +17,10 @@ See xref:title-page.adoc[] for details.
 
 |<<background-color,background-color>>
 |xref:color.adoc[Color] +
-(default: `'#ffffff'`)
+(default: `'FFFFFF'`)
 |[source]
 page:
-  background-color: '#fefefe'
+  background-color: #fefefe
 
 |<<images,background-image>>
 |image macro +
@@ -53,14 +53,14 @@ page:
   initial-zoom: Fit
 
 |layout
-|`portrait` {vbar} `landscape` +
+|`landscape` {vbar} `portrait` +
 (default: `portrait`)
 |[source]
 page:
   layout: landscape
 
 |margin
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]]+
+|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
 (default: `36`)
 |[source]
 page:
@@ -98,7 +98,7 @@ page:
 [#background-color]
 === Disable background-color
 
-To disable the background color for the page, set the value of `background-color` to white (i.e., `FFFFFF`).
+To disable the background color for the page, set the value of `background-color` to white (i.e., `#FFFFFF`).
 The color keyword `transparent` is not recognized in this context.
 
 [#images]
diff --git a/docs/modules/theme/pages/quoted-string.adoc b/docs/modules/theme/pages/quoted-string.adoc
index 6f1a4d25..506426da 100644
--- a/docs/modules/theme/pages/quoted-string.adoc
+++ b/docs/modules/theme/pages/quoted-string.adoc
@@ -14,7 +14,7 @@ If you need to add an underline or strikethrough decoration to the text, you can
 
 Here's an example of using formatting in the content of the menu caret:
 
-[source,yaml]
+[,yaml]
 ----
 menu-caret-content: " <font size=\"1.15em\"><color rgb=\"#b12146\">\u203a</color></font> "
 ----
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index 6d3539f4..cee23583 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -42,7 +42,7 @@ role:
     border-offset: 2
 
 |border-radius
-|xref:language.adoc#values[Number] +
+|xref:measurement-units.adoc[Measurement] +
 (default: _not set_)
 |[source]
 role:
@@ -50,7 +50,7 @@ role:
     border-radius: 3
 
 |border-width
-|xref:language.adoc#values[Number] +
+|xref:measurement-units.adoc[Measurement] +
 (default: _not set_)
 |[source]
 role:
@@ -67,7 +67,7 @@ role:
 
 |font-family
 |xref:font-support.adoc[Font family name] +
-(default: `Courier`)
+(default: _inherit_)
 |[source]
 role:
   label:
@@ -89,6 +89,14 @@ role:
   heavy:
     font-style: bold
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: _inherit_)
+|[source]
+role:
+  declare:
+    text-align: center
+
 |text-decoration
 |xref:text.adoc#decoration[Text decoration] +
 (default: `none`)
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc
index fbbba382..5f49e5a9 100644
--- a/docs/modules/theme/pages/running-content.adoc
+++ b/docs/modules/theme/pages/running-content.adoc
@@ -158,7 +158,7 @@ header:
 
 |margin
 |xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom(n/a),left\]] +
-(default: [`0`, `inherit`])
+(default: `[0, inherit]`)
 |[source]
 header:
   margin: 0
@@ -307,7 +307,6 @@ footer:
 footer:
   column-rule-style: dashed
 
-// TODO Since column-rule-style follows the pattern of border-style, does that mean column-rule-width follows the pattern of border-width?
 |column-rule-width
 |xref:measurement-units.adoc[Measurement] +
 (default: _not set_)
@@ -324,7 +323,7 @@ footer:
 
 |content-margin
 |xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
-(default: [`0`, `inherit`])
+(default: `[0, inherit]`)
 |[source]
 footer:
   content-margin: 0
@@ -445,7 +444,7 @@ footer:
 
 |<<side,<side>-margin>>
 |xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top (n/a),right,bottom,left\]] +
-(default: [`0`, `inherit`])
+(default: `[0, inherit]`)
 |[source]
 footer:
   verso:
diff --git a/docs/modules/theme/pages/sidebar.adoc b/docs/modules/theme/pages/sidebar.adoc
index 914bce76..3a930564 100644
--- a/docs/modules/theme/pages/sidebar.adoc
+++ b/docs/modules/theme/pages/sidebar.adoc
@@ -105,14 +105,6 @@ The keys in the `sidebar-title` category control the arrangement and style of si
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `center`)
-|[source]
-sidebar:
-  title:
-    text-align: left
-
 |font-color
 |xref:color.adoc[Color] +
 (default: _inherit_)
@@ -153,6 +145,14 @@ sidebar:
   title:
     font-style: bold_italic
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `center`)
+|[source]
+sidebar:
+  title:
+    text-align: left
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: _inherit_)
diff --git a/docs/modules/theme/pages/table.adoc b/docs/modules/theme/pages/table.adoc
index 3dba33b1..8f25c0b1 100644
--- a/docs/modules/theme/pages/table.adoc
+++ b/docs/modules/theme/pages/table.adoc
@@ -14,7 +14,6 @@ The keys in the `table` category control the arrangement and style of tables and
 |background-color
 |xref:color.adoc[Color] +
 (default: `transparent`)
-//TODO Where is the transparent value for the table background set in the base theme?
 |[source]
 table:
   background-color: #ffffff
@@ -41,7 +40,7 @@ table:
   border-width: 0.5
 
 |caption-align
-|xref:block.adoc#align[Alignment] {vbar} inherit +
+|xref:blocks.adoc#align[Block alignment] {vbar} inherit +
 (default: `$caption-align`)
 |[source]
 table:
@@ -167,6 +166,14 @@ table:
   head:
     border-bottom-width: 1
 
+|cell-padding
+|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+(default: `$table-cell-padding`)
+|[source]
+table:
+  head:
+    cell-padding: [4, 2]
+
 |font-color
 |xref:color.adoc[Color] +
 (default: `$table-font-color`)
@@ -215,14 +222,6 @@ table:
   head:
     line-height: 1.15
 
-|cell-padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
-(default: `$table-cell-padding`)
-|[source]
-table:
-  head:
-    cell-padding: [4, 2]
-
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: _inherit_)
@@ -310,7 +309,7 @@ table:
 
 |font-style
 |xref:text.adoc#font-style[Font style] +
-(default: `normal`)
+(default: `$table-font-style`)
 |[source]
 table:
   foot:
diff --git a/docs/modules/theme/pages/text.adoc b/docs/modules/theme/pages/text.adoc
index f85b7220..e94d387d 100644
--- a/docs/modules/theme/pages/text.adoc
+++ b/docs/modules/theme/pages/text.adoc
@@ -8,43 +8,51 @@ It has the same function as the `text-align` property in CSS.
 
 The text can be aligned using the following keywords:
 
-* `left`
-* `center`
-* `right`
-* `justify` (flush to each edge of the text box, if possible)
+`center`:: Text is centered within the text box.
+`justify`:: Text is spaced out to align evenly with both sides of the text box.
+`left`:: Text is aligned to the left side of the text box.
+`right`:: Text is aligned to the right side of the text box.
 
 The `text-align` key is distinct from the similarly-named `align` key.
-The latter key aligns a block element horizontally within its container.
+The xref:blocks.adoc#align[align key] aligns a block element horizontally within its container.
 
 [#decoration]
 == Decoration
 
-The following decorations can be applied to text:
+The `text-decoration` key specifies the type of decoration, such as an underline, that is applied to the text.
+It accepts the following keywords:
 
-* `none` (no decoration)
-* `underline`
-* `line-through`
+`line-through`:: A line is drawn across the text.
+This is commonly referred to as a strikethrough.
+`none`:: Clears an inherited value and no decoration is applied to the text.
+`underline`:: A line is drawn beneath the text.
+
+When a key category allows the `text-decoration` key to be set, you can usually specify a `text-decoration-color` and `text-decoration-width`, too.
 
 [#font-style]
 == Font style
 
-In most cases, wherever you can specify a custom font family, you can also specify a font style.
-These two settings are combined to locate the font to use.
+The `font-style` key specifies the font variant in a font family that the text should use.
+The key accepts the following keywords:
 
-The following font styles are recognized:
+`bold`:: Text is styled using the bold variant of a font family.
+`bold_italic`:: Text is styled using the bold italic variant of a font family
+`italic`:: Text is styled using the italic variant of a font family.
+`normal`:: Text is styled using the normal font variant in a font family.
+`normal_italic`:: The style of the text is reset to normal, and then the text is styled using the italic variant of a font family.
 
-* `normal` (no style)
-* `italic`
-* `bold`
-* `bold_italic`
+Usually, you can specify a font style wherever you can set a font family (`font-family`).
+The converter uses the values of both keys in combination to locate the correct font within a font stack.
 
 [#transform]
 == Transform
 
-Many places where font properties can be specified, a case transformation can be applied to the text.
-The following transforms are recognized:
+The `text-transform` key changes the case of the text.
+It accepts the following keywords:
+
+`capitalize`:: Transforms the first letter of each word to a capital letter.
+`none`:: Clears an inherited value and no case transformation is applied to the text.
+`lowercase`:: Transforms all the text to lower case letters.
+`uppercase`:: Transforms all the text to capital letters.
 
-* `uppercase`
-* `lowercase`
-* `capitalize` (each word, like CSS)
-* `none` (clears an inherited value)
+The `text-transform` key can’t be set on the xref:base.adoc[base category].
diff --git a/docs/modules/theme/pages/title-page.adoc b/docs/modules/theme/pages/title-page.adoc
index 29d580ae..10228b09 100644
--- a/docs/modules/theme/pages/title-page.adoc
+++ b/docs/modules/theme/pages/title-page.adoc
@@ -19,19 +19,12 @@ In that case, setting the `:notitle:` attribute only removes the document title
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `center`)
-|[source]
-title-page:
-  text-align: right
-
 |<<background-color,background-color>>
 |xref:color.adoc[Color] +
 (default: _inherit_)
 |[source]
 title-page:
-  background-color: '#eaeaea'
+  background-color: #eaeaea
 
 |<<background-image,background-image>>
 |image macro +
@@ -45,7 +38,7 @@ title-page:
 (default: _inherit_)
 |[source]
 title-page:
-  font-color: '#333333'
+  font-color: #333333
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -82,6 +75,13 @@ title-page:
 title-page:
   line-height: 1
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `center`)
+|[source]
+title-page:
+  text-align: right
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: _inherit_)
@@ -115,7 +115,7 @@ The keys in the `title-page-logo` category control the arrangement of a logo on
 |Key |Value Type |Example
 
 |align
-|xref:image.adoc#align[Image alignment] +
+|xref:blocks.adoc#align[Block alignment] +
 (default: `$title-page-text-align`)
 |[source]
 title-page:
@@ -172,7 +172,7 @@ title-page:
 |[source]
 title-page:
   title:
-    font-color: '#999999'
+    font-color: #999999
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -271,7 +271,7 @@ title-page:
 |[source]
 title-page:
   subtitle:
-    font-color: '#181818'
+    font-color: #181818
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -380,7 +380,7 @@ title-page:
 |[source]
 title-page:
   authors:
-    font-color: '#181818'
+    font-color: #181818
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -475,7 +475,7 @@ title-page:
 |[source]
 title-page:
   revision:
-    font-color: '#181818'
+    font-color: #181818
 
 |font-family
 |xref:font-support.adoc[Font family name] +
diff --git a/docs/modules/theme/pages/toc.adoc b/docs/modules/theme/pages/toc.adoc
index ec8c93f2..f174bbdb 100644
--- a/docs/modules/theme/pages/toc.adoc
+++ b/docs/modules/theme/pages/toc.adoc
@@ -16,7 +16,7 @@ The keys in the `toc` category control the arrangement and style of the table of
 (default: _inherit_)
 |[source]
 toc:
-  font-color: '#333333'
+  font-color: #333333
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -87,7 +87,7 @@ toc:
 (default: `$toc-font-color`)
 |[source]
 toc:
-  text-decoration-color: '#cccccc'
+  text-decoration-color: #cccccc
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -119,7 +119,7 @@ The keys in the `toc-h<n>` category control the arrangement and style of each he
 (default: _inherit_)
 |[source]
 toc:
-  h3-font-color: '#999999'
+  h3-font-color: #999999
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -166,21 +166,13 @@ The keys in the `toc-title` category control the arrangement and style of the ti
 |===
 |Key |Value Type |Example
 
-|text-align
-|xref:text.adoc#text-align[Text alignment] +
-(default: `$heading-h2-text-align`)
-|[source]
-toc:
-  title:
-    text-align: right
-
 |font-color
 |xref:color.adoc[Color] +
 (default: `$heading-h2-font-color`)
 |[source]
 toc:
   title:
-    font-color: '#aa0000'
+    font-color: #aa0000
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -214,6 +206,14 @@ toc:
   title:
     font-style: bold_italic
 
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$heading-h2-text-align`)
+|[source]
+toc:
+  title:
+    text-align: right
+
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: `$heading-h2-text-transform`)
@@ -246,7 +246,7 @@ toc:
 |[source]
 toc:
   dot-leader:
-    font-color: '#999999'
+    font-color: #999999
 
 |<<font-style,font-style>>
 |xref:text.adoc#font-style[Font style] +
diff --git a/docs/modules/theme/pages/variables.adoc b/docs/modules/theme/pages/variables.adoc
index 8f4a7b0e..f8253503 100644
--- a/docs/modules/theme/pages/variables.adoc
+++ b/docs/modules/theme/pages/variables.adoc
@@ -16,10 +16,10 @@ In other words, the path the variable refers to must be *above* the usage of tha
 
 For example, once the following line is processed,
 
-[source,yaml]
+[,yaml]
 ----
 base:
-  font-color: '#333333'
+  font-color: #333333
 ----
 
 the variable `$base-font-color` will be available for use in subsequent lines and will resolve to `#333333`.
@@ -27,10 +27,10 @@ the variable `$base-font-color` will be available for use in subsequent lines an
 Let's say you want to make the font color of the sidebar title the same as the heading font color.
 Just assign the value `$heading-font-color` to the `$sidebar-title-font-color`.
 
-[source,yaml]
+[,yaml]
 ----
 heading:
-  font-color: '#191919'
+  font-color: #191919
 sidebar:
   title:
     font-color: $heading-font-color
@@ -42,7 +42,7 @@ You can also use variables in math expressions to use one value to build another
 This is commonly done to set font sizes proportionally.
 It also makes it easy to test different values very quickly.
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-size: 12
@@ -61,22 +61,22 @@ 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,subs=attributes+]
+[,yaml,subs=attributes+]
 ----
 brand:
-  primary-color: '#E0162B' {conum-guard-yaml} <1>
+  primary-color: #E0162B {conum-guard-yaml} <1>
   secondary-color: '#FFFFFF' {conum-guard-yaml} <2>
   alert-color: '0052A5' {conum-guard-yaml} <3>
 ----
 <1> To align with CSS, you may add `+#+` in front of the hex color value to coerce it to a string.
 A YAML preprocessor is used to ensure the value is not treated as a comment as would normally be the case in YAML.
-<2> You may put quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool.
+<2> You may put single quotes around the CSS-style hex value to make it friendly to a YAML editor or validation tool.
 <3> The leading `+#+` on a hex value is entirely optional.
 However, we recommend that you always use either a leading `+#+` or surrounding quotes (or both) to prevent YAML from mangling the value (for example, 000000 would become 0, so use '000000' or #000000 instead).
 
 You can now use these custom variables later in the theme file:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-color: $brand-primary-color
diff --git a/docs/modules/theme/pages/verse.adoc b/docs/modules/theme/pages/verse.adoc
index d046ce5b..600ccf5a 100644
--- a/docs/modules/theme/pages/verse.adoc
+++ b/docs/modules/theme/pages/verse.adoc
@@ -40,7 +40,7 @@ code:
   border-radius: 4
 
 |border-style
-|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid`  {vbar} +
+|`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
 (default: `solid`)
 |[source]
 verse:
@@ -141,7 +141,7 @@ verse:
     font-family: Noto Serif
 
 |font-kerning
-|normal {vbar} none +
+|`normal` {vbar} `none` +
 (default: _inherit_)
 |[source]
 verse: