update padding key information (PR #2169)

52 files changed, 358 insertions, 285 deletions

diff --git a/docs/modules/theme/pages/abstract.adoc b/docs/modules/theme/pages/abstract.adoc
index f6182b0f..635e08f5 100644
--- a/docs/modules/theme/pages/abstract.adoc
+++ b/docs/modules/theme/pages/abstract.adoc
@@ -1,4 +1,5 @@
 = Abstract Category Keys
+:description: Reference list of the available abstract category keys and their value types.
 :navtitle: Abstract
 :source-language: yaml
 
@@ -16,7 +17,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] +
@@ -40,7 +41,7 @@ abstract:
   line-height: 1.2
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `0`)
 |[source]
 abstract:
@@ -58,7 +59,7 @@ abstract:
 (default: `$abstract-font-color`)
 |[source]
 abstract:
-  text-decoration-color: #0000ff
+  text-decoration-color: #0000FF
 
 |text-decoration-width
 |xref:measurement-units.adoc[Measurement] +
@@ -72,7 +73,7 @@ abstract:
 (default: _inherit_)
 |[source]
 abstract:
-  text-transform: uppercase
+  text-transform: none
 |===
 
 [#first-line]
@@ -134,7 +135,7 @@ abstract:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 abstract:
@@ -179,7 +180,7 @@ abstract:
 |[source]
 abstract:
   title:
-    text-decoration-color: #0000ff
+    text-decoration-color: #0000FF
 
 |text-decoration-width
 |xref:measurement-units.adoc[Measurement] +
diff --git a/docs/modules/theme/pages/admonition.adoc b/docs/modules/theme/pages/admonition.adoc
index 6dd1fadb..cfcf3180 100644
--- a/docs/modules/theme/pages/admonition.adoc
+++ b/docs/modules/theme/pages/admonition.adoc
@@ -1,4 +1,5 @@
 = Admonition Category Keys
+:description: Reference list of the available admonition category keys and their value types.
 :navtitle: Admonition
 :source-language: yaml
 
@@ -23,7 +24,7 @@ admontition:
 (default: _not set_)
 |[source]
 admonition:
-  border-color: #e6e8fa
+  border-color: #E6E8FA
 
 |border-radius
 |xref:blocks.adoc#radius[Measurement] +
@@ -53,7 +54,7 @@ verse:
 (default: `'EEEEEE'`)
 |[source]
 admonition:
-  column-rule-color: #aa0000
+  column-rule-color: #AA0000
 
 |column-rule-style
 |`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
@@ -84,7 +85,7 @@ admonition:
   font-family: Noto Sans
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 admonition:
@@ -105,11 +106,11 @@ admonition:
   font-style: italic
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `[4, 12, 4, 12]`)
 |[source]
 admonition:
-  padding: [0, 14, 0, 14]
+  padding: 1cm
 
 |text-transform
 |xref:text.adoc#transform[Text transform] +
@@ -145,7 +146,7 @@ admonition:
     font-family: M+ 1p
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 admonition:
@@ -201,7 +202,7 @@ admonition:
     text-transform: lowercase
 
 |vertical-align
-|`top` {vbar} `middle` {vbar} `bottom` +
+|`bottom` {vbar} `middle` {vbar} `top` +
 (default: `middle`)
 |[source]
 admonition:
@@ -243,7 +244,7 @@ admonition:
       font-family: M+ 1p
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 admonition:
@@ -312,12 +313,12 @@ admonition:
 
 |stroke-color
 |xref:color.adoc[Color] +
-(default: caution=`#bf3400`; important=`#bf0000`; note=`#19407c`; tip=`#111111`; warning=`#bf6900`)
+(default: caution=`#BF3400`; important=`#BF0000`; note=`#19407C`; tip=`#111111`; warning=`#BF6900`)
 |[source]
 admonition:
   icon:
     important:
-      stroke-color: #ff0000
+      stroke-color: #FF0000
 |===
 
 [#name]
diff --git a/docs/modules/theme/pages/base.adoc b/docs/modules/theme/pages/base.adoc
index c747e458..6b78d41f 100644
--- a/docs/modules/theme/pages/base.adoc
+++ b/docs/modules/theme/pages/base.adoc
@@ -1,4 +1,5 @@
 = Base Category Keys
+:description: Reference list of the available base category keys and their value types. The base category provides generic theme settings.
 :source-language: yaml
 :navtitle: Base
 
@@ -19,7 +20,7 @@ TIP: While it's common to define additional keys in this category (e.g., `base-b
 (default: `'EEEEEE'`)
 |[source]
 base:
-  border-color: #f0fff0
+  border-color: #F0FFF0
 
 |border-width
 |xref:measurement-units.adoc[Measurement] +
@@ -43,7 +44,7 @@ base:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: `normal`)
 |[source]
 base:
@@ -105,7 +106,7 @@ base:
 (default: `$base-font-color`)
 |[source]
 base:
-  text-decoration-color: #0000ff
+  text-decoration-color: #0000FF
 
 |text-decoration-width
 |xref:measurement-units.adoc[Measurement] +
diff --git a/docs/modules/theme/pages/block-image.adoc b/docs/modules/theme/pages/block-image.adoc
index 978eca40..67b639f8 100644
--- a/docs/modules/theme/pages/block-image.adoc
+++ b/docs/modules/theme/pages/block-image.adoc
@@ -154,16 +154,16 @@ Most of the keys listed on xref:caption.adoc[] can also be nested under the `ima
 |===
 |Key |Value Type |Example
 
-|caption-align
-|xref:blocks.adoc#align[Block alignment] {vbar} xref:blocks.adoc#caption-align[inherit] +
+|xref:block-images.adoc#caption-align[caption-align]
+|xref:block-images.adoc#caption-align[Block alignment] {vbar} xref:block-images.adoc#caption-align[inherit] +
 (default: `$caption-align`)
 |[source]
 image:
   caption:
     align: inherit
 
-|caption-end
-|<<caption-end,bottom>> {vbar} <<caption-end,top>> +
+|xref:block-images.adoc#end[caption-end]
+|xref:block-images.adoc#end[End placement] +
 (default: `bottom`)
 |[source]
 image:
@@ -178,8 +178,8 @@ image:
   caption:
     max-width: fit-content
 
-|caption-text-align
-|xref:text.adoc#text-align[Text alignment] {vbar} <<caption-text-align,inherit>> +
+|xref:block-images.adoc#caption-text-align[caption-text-align]
+|xref:block-images.adoc#caption-text-align[Text alignment] {vbar} xref:block-images.adoc#caption-text-align[inherit] +
 (default: `$image-caption-align`)
 |[source]
 image:
@@ -187,27 +187,9 @@ image:
     text-align: center
 |===
 
-[#caption-end]
-== Caption end
+// DANGER! Do not describe or add extra information about the block image caption keys here! Such information, examples, etc., belongs on the block-images.adoc page. The caption max width section below will be moved there once there's time to document it.
 
-The `caption-end` key specifies whether the image caption is located on top or below the image.
-The key accepts the following keywords:
-
-bottom:: The caption block is placed below the bottom of the image.
-top:: The caption block is place above the top of the image.
-
-[,yaml]
-----
-image:
-  caption:
-    end: top
-----
-
-[#caption-text-align]
-=== Caption text align
-
-Controls the alignment of the caption text within the bounds of the caption.
-If the value is `inherit`, it will inherit the alignment of the image itself.
+// Seriously. I've got velociraptors and green slime.
 
 [#caption-max-width]
 === Caption max width
diff --git a/docs/modules/theme/pages/block-images.adoc b/docs/modules/theme/pages/block-images.adoc
index e8a9e21c..f9d15e53 100644
--- a/docs/modules/theme/pages/block-images.adoc
+++ b/docs/modules/theme/pages/block-images.adoc
@@ -1,10 +1,25 @@
 = Block Image Styles
 :description: In addition to the general block and caption keys, the theming language provides keys for arranging and styling block images, alt text, and image captions.
 
-You can customize how the block images, alt text, and image captions are arranged and styled using the xref:block-image.adoc[] and the xref:caption.adoc[].
-In general, the xref:blocks.adoc[] and xref:caption.adoc[] apply to block images and their captions.
-You can further customize how the block images, alt text, and image captions are arranged and styled using the xref:block-image.adoc[].
-The following sections provide additional information about the keys that are unique to the block images.
+In general, the xref:blocks.adoc[] apply to block images and their captions.
+You can further customize how the block images, alt text, and captions are arranged and styled using the xref:block-image.adoc[].
+The following sections provide information and examples about the keys and values that are unique to the block images.
+
+[#caption-align]
+== Caption alignment
+
+In addition to the xref:blocks.adoc#align[standard block alignment keywords (center, left, and right)], the `caption-align` key accepts the keyword `inherit` when it is set on the `image` category.
+
+[,yaml]
+----
+image:
+  caption:
+    align: inherit
+----
+
+When the value is `inherit`, the key will inherit the alignment assigned to the image itself (`image-align`).
+The `caption-align` key is distinct from the similarly-named `caption-text-align` key.
+The <<caption-text-align,caption-text-align key>> aligns text within the text box of the caption block using text alignment rules.
 
 [#end]
 == Caption end
@@ -25,7 +40,8 @@ image:
 [#caption-text-align]
 == Caption text alignment
 
-The `caption-text-align` key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `image` category.
+The `caption-text-align` key controls the alignment of the caption text within the bounds of the caption.
+The key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `image` category.
 
 [,yaml]
 ----
@@ -34,4 +50,7 @@ image:
     text-align: inherit
 ----
 
-The value `inherit` resolves to the block alignment (`image-align`) assigned to the `image` category.
+When the value is `inherit`, the key will inherit the alignment assigned to the image itself (`image-align`).
+
+The `caption-text-align` key is distinct from the similarly-named `caption-align` key.
+The <<caption-align,caption-align key>> aligns a caption block horizontally within its container.
diff --git a/docs/modules/theme/pages/block.adoc b/docs/modules/theme/pages/block.adoc
index 31b46ef1..525f4bfa 100644
--- a/docs/modules/theme/pages/block.adoc
+++ b/docs/modules/theme/pages/block.adoc
@@ -1,9 +1,26 @@
 = Block Category Keys
+:description: Reference list of the available global block category keys and their value types.
 :navtitle: Block
 :source-language: yaml
 
 The keys in the `block` category control the anchor position and spacing below block elements when a more specific setting isn't designated.
-The bottom margin is only added if the block is followed by an adjacent block within the same enclosure (e.g., a sidebar, a table cell, or the area outside any blocks).
+Block styles are applied to the following block types:
+
+[cols="2*a",width=75%,grid=none,frame=none]
+|===
+|
+* admonition
+* block image
+* code (listing, literal, source)
+* example
+|
+* quote
+* sidebar
+* table
+* verse
+|===
+
+The bottom margin (`margin-bottom`) is only added if the block is followed by an adjacent block within the same enclosure (e.g., a sidebar, a table cell, or the area outside any blocks).
 
 [cols="3,4,6a"]
 |===
@@ -23,21 +40,3 @@ block:
 block:
   margin-bottom: 6
 |===
-
-Block styles are applied to the following block types:
-
-[cols="3*a",grid=none,frame=none]
-|===
-|
-* admonition
-* example
-* quote
-|
-* verse
-* sidebar
-* image
-|
-* listing
-* literal
-* table
-|===
diff --git a/docs/modules/theme/pages/blocks.adoc b/docs/modules/theme/pages/blocks.adoc
index a6348db8..e706ac86 100644
--- a/docs/modules/theme/pages/blocks.adoc
+++ b/docs/modules/theme/pages/blocks.adoc
@@ -15,24 +15,13 @@ The block can be aligned using the following keywords:
 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.
+inherit:: *Only applies to the captions of block images (`image-caption`) and tables (`table-caption`).*
+The value `inherit` resolves to the alignment of the block image or table.
+Further information about using `inherit` on image captions and table captions, can be found on xref xref:block-images.adoc#caption-align[Block Image Styles] and xref:tables.adoc#caption-align[Table Styles], respectively.
 
 The `align` key is distinct from the similarly-named `text-align` key.
 The xref:text.adoc#text-align[text-align key] aligns text within the text box using text alignment rules.
 
-[#caption-align]
-=== Caption alignment
-
-In addition to the alignment keywords listed in the <<align>> section, the `caption-align` key accepts the keyword `inherit` when it is set on the `image` or `table` category.
-
-[,yaml]
-----
-image:
-  caption:
-    align: inherit
-----
-
-The value `inherit` resolves to the alignment of the block image or table.
-
 [#border-width]
 == Border width
 
@@ -83,12 +72,12 @@ The `border-color` key specifies the color of a border.
 It accepts the following types of values:
 
 Hex, RGB, or CMYK color:: A single color specified using the hex, RGB, or CMYK format.
-See xref:color.adoc[] to learn how to assign a value using these formats in the theming language.
+See xref:color.adoc[] to learn how to assign these formats in the theming language.
 transparent:: A special keyword that indicates a color should not be used when drawing the border.
 Array of colors:: *Only applies to the `table` category*.
 An array that specifies xref:tables.adoc#border-color[a color per edge on tables].
 
-The value assigned to `border-color` is ignored if `border-width` isn't implicitly or explicitly set or is set to `0` on the category.
+The `border-color` key value is ignored if `border-width` isn't set or is set to `0` on the category.
 
 [#radius]
 == Border radius
@@ -103,7 +92,7 @@ sidebar:
   border-radius: 2
 ----
 
-The value assigned to the `border-radius` key is ignored if `border-width` is assigned an array of values.
+The `border-radius` key value is ignored if `border-width` is assigned an array of values.
 The `border-radius` key can't be set on the `table` category.
 
 [#border-style]
@@ -120,4 +109,49 @@ solid:: The border is drawn as a straight, single line.
 Array of styles:: *Only applies to the `table` category*.
 An array that specifies xref:tables.adoc#border-style[a style per edge on tables].
 
-The value assigned to a `border-style` key is ignored on a block category if `border-width` isn't implicitly or explicitly set or `border-width` is set to `0` on the category.
+The `border-style` key value is ignored on a block category if `border-width` isn't set or `border-width` is set to `0` on the category.
+
+[#padding]
+== Padding
+
+Several of the block categories, such as `admonition`, `sidebar`, `verse`, etc., allow their padding to be customized.
+The `padding` key specifies the amount of space between a block's content and its border.
+The key accepts a single measurement value or an array of measurements.
+When a single value is assigned to `padding`, the same amount of padding is applied to all four sides.
+
+.Single value assigned to padding
+[,yaml]
+----
+quote:
+  padding: 1.2mm <1>
+----
+<1> You don't need to enclose a single value in a set of square brackets.
+
+When a 2-value array is assigned to `padding`, the first value is applied to the top and bottom padding, and the second value is applied to the left and right side padding.
+
+.Two-value array assigned to padding
+[,yaml]
+----
+sidebar:
+  padding: [0.5, 2]
+----
+
+When a 4-value array is assigned to `padding`, the first value is applied to the top, the second to the right side, the third to the bottom, and the fourth to the left side padding.
+
+.Four-value array assigned to padding
+[,yaml]
+----
+code:
+  padding: [0.75in, 0, 2in, 0.5in]
+----
+
+The `padding` key also accepts a 3-value array, where the first value is applied to the top, the second to the right and left side, and the third to the bottom.
+
+////
+[#margin]
+== Margins
+
+The `margin` key specifies the amount of space around the outermost edges of a block.
+The key accepts a single measurement value or an array of measurements.
+When a single value is assigned to `margin`, the same amount of margin is applied to all four sides.
+////
diff --git a/docs/modules/theme/pages/button.adoc b/docs/modules/theme/pages/button.adoc
index 18c727fd..88ebe78e 100644
--- a/docs/modules/theme/pages/button.adoc
+++ b/docs/modules/theme/pages/button.adoc
@@ -1,4 +1,5 @@
 = Button Macro Category Keys
+:description: Reference list of the available button UI macro category keys and their value types.
 :navtitle: Button
 :source-language: yaml
 
@@ -16,14 +17,14 @@ The keys in the `button` category apply to a button reference generated from the
 (default: _not set_)
 |[source]
 button:
-  background-color: #0000ff
+  background-color: #0000FF
 
 |<<border-color,border-color>>
 |xref:color.adoc[Color] +
 (default: _not set_)
 |[source]
 button:
-  border-color: #cccccc
+  border-color: #CCCCCC
 
 |<<border-offset,border-offset>>
 |xref:language.adoc#values[Number] +
@@ -58,7 +59,7 @@ button:
 (default: _inherit_)
 |[source]
 button:
-  font-color: #ffffff
+  font-color: #FFFFFF
 
 |font-family
 |xref:font-support.adoc[Font family name] +
diff --git a/docs/modules/theme/pages/callout.adoc b/docs/modules/theme/pages/callout.adoc
index 4bfa292d..f5a3a034 100644
--- a/docs/modules/theme/pages/callout.adoc
+++ b/docs/modules/theme/pages/callout.adoc
@@ -1,4 +1,5 @@
 = Callout List and Number Category Keys
+:description: Reference list of the available callout list and callout number (conum) category keys and their value types.
 :navtitle: Callout List and Number
 :source-language: yaml
 
@@ -102,7 +103,7 @@ Also see <<inherit>> for more information.
 (default: _inherit_)
 |[source]
 conum:
-  font-color: #b12146
+  font-color: #B12146
 
 |<<glyphs,font-family>>
 |xref:font-support.adoc[Font family name] +
@@ -112,7 +113,7 @@ conum:
   font-family: M+ 1mn
 
 |<<inherit,font-kerning>>
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 conum:
diff --git a/docs/modules/theme/pages/caption.adoc b/docs/modules/theme/pages/caption.adoc
index 2dd7a003..3cbf8204 100644
--- a/docs/modules/theme/pages/caption.adoc
+++ b/docs/modules/theme/pages/caption.adoc
@@ -1,12 +1,13 @@
 = Caption Category Keys
+:description: Reference list of the available global caption category keys and their value types.
 :navtitle: Caption
 :source-language: yaml
 
 The keys in the `caption` category control the arrangement and style of block captions globally.
-In addition to this global `caption` category, each of these keys, except for the `text-decoration` keys, can be set on the caption key nested inside the following block categories: `quote`, `code`, `example`, `footnotes`, `image`, `table`, and `verse`.
+In addition to this global `caption` category, each of the keys listed below, except for the `text-decoration` keys, can be set on the caption key nested inside the following block categories: `code`, `example`, `footnotes`, `image`, `quote`, `table`, and `verse`.
 
-The `caption-align` and `caption-text-align` keys, when nested on the `image` or `table` category, also accept the value `inherit`.
-See xref:blocks.adoc#caption-align[Caption alignment] and xref:text.adoc#caption-text-align[Caption text alignment] for more information.
+TIP: The `caption-align` and `caption-text-align` keys, when nested on the `image` or `table` category, also accept the value `inherit`.
+See xref:block-images.adoc[] and xref:tables.adoc[] for more information about setting `inherit` on their captions.
 
 [cols="3,4,5a"]
 |===
@@ -41,7 +42,7 @@ caption:
   font-family: M+ 1mn
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 caption:
diff --git a/docs/modules/theme/pages/cjk.adoc b/docs/modules/theme/pages/cjk.adoc
index 60c87334..d55c17fd 100644
--- a/docs/modules/theme/pages/cjk.adoc
+++ b/docs/modules/theme/pages/cjk.adoc
@@ -16,12 +16,12 @@ Just make sure you download the TTF variant.
 Once you have downloaded the fonts, place the files into the directory where you are going to create your theme.
 For the purpose of this guide, we'll assume you are working with the following font files:
 
-* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansCJKsc-VF.ttf]
-* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansMonoCJKsc-VF.ttf]
+* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansCJKsc-VF.ttf^]
+* https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf[NotoSansMonoCJKsc-VF.ttf^]
 
-If you'd like to use different fonts, refer to the https://en.wikipedia.org/wiki/List_of_CJK_fonts[list of notable CJK fonts on Wikipedia].
+If you'd like to use different fonts, refer to the https://en.wikipedia.org/wiki/List_of_CJK_fonts[list of notable CJK fonts on Wikipedia^].
 With that information, you can search for the TTF font on any font service.
-You can also find the Kai Gen Gothic fonts for CJK languages in TTF format on the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases[releases page] for the now deprecated asciidoctor-pdf-cjk-kai_gen_gothic project.
+You can also find the Kai Gen Gothic fonts for CJK languages in TTF format on the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases[releases page^] for the now deprecated asciidoctor-pdf-cjk-kai_gen_gothic project.
 
 == Create the theme file
 
@@ -67,14 +67,12 @@ You may also want to darken the font color since the Noto Sans SC font has a thi
 
 [,yaml]
 ----
-...
 base:
   text-align: left
   font-color: #000000
   font-family: Noto Sans CN
 heading:
   font-color: #000000
-...
 ----
 
 You may need to adjust the font color on other keys as well.
diff --git a/docs/modules/theme/pages/code.adoc b/docs/modules/theme/pages/code.adoc
index c7db5a14..12b77d2e 100644
--- a/docs/modules/theme/pages/code.adoc
+++ b/docs/modules/theme/pages/code.adoc
@@ -1,4 +1,5 @@
 = Code Block Category Keys
+:description: Reference list of the available code block (listing, literal, and source) category keys and their value types.
 :navtitle: Code Block
 :source-language: yaml
 
@@ -16,14 +17,14 @@ The keys in the `code` category control the arrangement and style of literal, li
 (default: _not set_)
 |[source]
 code:
-  background-color: #f5f5f5
+  background-color: #F5F5F5
 
 |border-color
 |xref:blocks.adoc#border-color[Color] +
 (default: `'EEEEEE'`)
 |[source]
 code:
-  border-color: #cccccc
+  border-color: #CCCCCC
 
 |border-radius
 |xref:blocks.adoc#radius[Measurement] +
@@ -89,11 +90,11 @@ code:
   line-height: 1.25
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `9`)
 |[source]
 code:
-  padding: 11
+  padding: 12mm
 |===
 
 [#line-gap]
@@ -116,7 +117,7 @@ Otherwise, the background color is controlled by the source highlighter theme.
 (default: `#FFFFCC`)
 |[source]
 code:
-  highlight-background-color: #ffff00
+  highlight-background-color: #FFFF00
 |===
 
 [#linenum]
@@ -134,6 +135,6 @@ Otherwise, the font color of line numbers are controlled by the source highlight
 (default: `#999999`)
 |[source]
 code:
-  linenum-font-color: #ccc
+  linenum-font-color: #CCCCCC
 |===
 
diff --git a/docs/modules/theme/pages/codespan.adoc b/docs/modules/theme/pages/codespan.adoc
index 5a7dfa06..c119b89a 100644
--- a/docs/modules/theme/pages/codespan.adoc
+++ b/docs/modules/theme/pages/codespan.adoc
@@ -1,4 +1,5 @@
 = Codespan Category Keys
+:description: Reference list of the available codespan (inline monospace text in prose and table cells) category keys and their value types.
 :navtitle: Codespan
 :source-language: yaml
 
@@ -16,14 +17,14 @@ The keys in the `codespan` category are used for inline monospace text in prose
 (default: _not set_)
 |[source]
 codespan:
-  background-color: #f5f5f5
+  background-color: #F5F5F5
 
 |<<border-color,border-color>>
 |xref:color.adoc[Color] +
 (default: _not set_)
 |[source]
 codespan:
-  border-color: #cccccc
+  border-color: #CCCCCC
 
 |<<border-offset,border-offset>>
 |xref:language.adoc#values[Number] +
@@ -51,7 +52,7 @@ codespan:
 (default: _inherit_)
 |[source]
 codespan:
-  font-color: #b12146
+  font-color: #B12146
 
 |font-family
 |xref:font-support.adoc[Font family name] +
diff --git a/docs/modules/theme/pages/color.adoc b/docs/modules/theme/pages/color.adoc
index 2ba2094b..ab69e4cf 100644
--- a/docs/modules/theme/pages/color.adoc
+++ b/docs/modules/theme/pages/color.adoc
@@ -1,4 +1,5 @@
 = Colors
+:description: The theming language supports color values in hex, RGB, and CMYK formats.
 
 The theme language supports color values in three formats:
 
diff --git a/docs/modules/theme/pages/custom-font.adoc b/docs/modules/theme/pages/custom-font.adoc
index bd270edc..0041573c 100644
--- a/docs/modules/theme/pages/custom-font.adoc
+++ b/docs/modules/theme/pages/custom-font.adoc
@@ -43,7 +43,7 @@ Rename the files as follows:
 Next, declare the font under the `font-catalog` key at the top of your theme file.
 Assign each font a unique key (e.g., `Roboto`) and specify the path to each of the four font styles under that key.
 
-[source,yaml,subs=attributes+]
+[,yaml,subs=attributes+]
 ----
 font:
   catalog:
@@ -61,7 +61,7 @@ If you're missing the font file for one of the variants, configure it to use the
 
 If your font only has a single variant, assign the font path to the font key directly.
 
-[source,yaml,subs=attributes+]
+[,yaml,subs=attributes+]
 ----
 font:
   catalog:
@@ -78,7 +78,7 @@ You can also use the `GEM_FONTS_DIR` keyword to refer to the location of the bun
 You can add any number of fonts to the catalog.
 Each font must be assigned a unique key, as shown here:
 
-[source,yaml,subs=attributes+]
+[,yaml,subs=attributes+]
 ----
 font:
   catalog:
@@ -99,7 +99,7 @@ font:
 You can use the key that you assign to the font in the font catalog anywhere the `font-family` property is accepted in the theme file.
 For example, to use the Roboto font for all headings (section titles and discrete headings), use:
 
-[source,yaml]
+[,yaml]
 ----
 heading:
   font-family: Roboto
diff --git a/docs/modules/theme/pages/custom-role.adoc b/docs/modules/theme/pages/custom-role.adoc
index 3f1a0b31..5ed0db08 100644
--- a/docs/modules/theme/pages/custom-role.adoc
+++ b/docs/modules/theme/pages/custom-role.adoc
@@ -13,7 +13,7 @@ The name of a custom role may contain a hyphen, but *a role name cannot contain
 ----
 role: <.>
   rolename: <.>
-    font-color: #ff7f50 <.>
+    font-color: #FF7F50 <.>
     font-style: bold
     text-decoration: underline
   another-role: <.>
@@ -39,7 +39,7 @@ The keys `background-color` and `font-color` are set and each key is assigned a
 role:
   red:
     background-color: #333333
-    font-color: #ff0000
+    font-color: #FF0000
 ----
 
 You can also use a custom role to unset the default styling of a paragraph or inline phrase and make it inherit the styling of its parent element.
diff --git a/docs/modules/theme/pages/description-list.adoc b/docs/modules/theme/pages/description-list.adoc
index a7f24ff5..8c214129 100644
--- a/docs/modules/theme/pages/description-list.adoc
+++ b/docs/modules/theme/pages/description-list.adoc
@@ -1,4 +1,5 @@
 = Description List Category Keys
+:description: Reference list of the available description term and list category keys and their value types.
 :navtitle: Description List
 :source-language: yaml
 
@@ -33,7 +34,7 @@ description-list:
   term-font-family: Noto Serif
 
 |term-font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 description-list:
@@ -72,7 +73,7 @@ description-list:
 (default: `none`)
 |[source]
 description-list:
-  term-text-transform: none
+  term-text-transform: smallcaps
 |===
 
 == Ordered and unordered description lists
diff --git a/docs/modules/theme/pages/example.adoc b/docs/modules/theme/pages/example.adoc
index 1a3630ce..5105665a 100644
--- a/docs/modules/theme/pages/example.adoc
+++ b/docs/modules/theme/pages/example.adoc
@@ -1,4 +1,5 @@
 = Example Category Keys
+:description: Reference list of the available example block category keys and their value types.
 :navtitle: Example
 :source-language: yaml
 
@@ -13,7 +14,7 @@ The keys in the `example` category control the arrangement and style of example
 (default: `'FFFFFF'`)
 |[source]
 example:
-  background-color: #fffef7
+  background-color: #FFFEF7
 
 |border-color
 |xref:blocks.adoc#border-color[Color] +
@@ -58,7 +59,7 @@ example:
   font-family: M+ 1p
 
 |font-kerning
-|normal {vbar} none +
+|none {vbar} normal +
 (default: _inherit_)
 |[source]
 example:
@@ -79,7 +80,7 @@ example:
   font-style: italic
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `12`)
 |[source]
 example:
diff --git a/docs/modules/theme/pages/extend-theme.adoc b/docs/modules/theme/pages/extend-theme.adoc
index d94f19e7..e845ecf2 100644
--- a/docs/modules/theme/pages/extend-theme.adoc
+++ b/docs/modules/theme/pages/extend-theme.adoc
@@ -11,7 +11,7 @@ For example:
 ----
 extends: default
 base:
-  font-color: #ff0000
+  font-color: #FF0000
 ----
 
 The `extends` key accepts either a single value or an array of values.
@@ -48,7 +48,7 @@ role:
   removed:
     font-style: italic
     text-decoration: line-through
-    text-decoration-color: #ff0000
+    text-decoration-color: #FF0000
 heading:
   font-color: #262626
   font-size: 17
@@ -81,7 +81,7 @@ Instead of designing a theme from scratch, you can extend the default theme usin
 ----
 extends: default
 base:
-  font-color: #ff0000
+  font-color: #FF0000
 ----
 
 You can also point the `extends` key at another custom theme to extend from it.
diff --git a/docs/modules/theme/pages/extends.adoc b/docs/modules/theme/pages/extends.adoc
index 9eabde12..e9a5b17c 100644
--- a/docs/modules/theme/pages/extends.adoc
+++ b/docs/modules/theme/pages/extends.adoc
@@ -1,4 +1,5 @@
 = Extends Category Key
+:description: Reference list of the extends category key and its value types.
 :navtitle: Extends
 :source-language: yaml
 
diff --git a/docs/modules/theme/pages/fallback-font.adoc b/docs/modules/theme/pages/fallback-font.adoc
index 445bf47b..b60a3e6e 100644
--- a/docs/modules/theme/pages/fallback-font.adoc
+++ b/docs/modules/theme/pages/fallback-font.adoc
@@ -22,7 +22,7 @@ Like with other custom fonts, you first need to declare the fallback font.
 Let's choose https://github.com/android/platform_frameworks_base/blob/master/data/fonts/DroidSansFallback.ttf[Droid Sans Fallback^].
 You can map all the styles to a single font file (since bold and italic don't usually make sense for symbols).
 
-[source,yaml]
+[,yaml]
 ----
 font:
   catalog:
@@ -38,7 +38,7 @@ Notice that we only declare the fallback font file once using a literal value.
 This ensures the font is defined for all four variants so it will be used regardless of which font style is active when it's called on.
 This assignment is equivalent to the following:
 
-[source,yaml]
+[,yaml]
 ----
 DroidSansFallback:
   '*': droid-sans-fallback.ttf
@@ -50,7 +50,7 @@ Next, add the key name to the `fallbacks` key under the `font-catalog` key.
 The xref:font.adoc[fallbacks key] accepts an array of values, meaning you can specify more than one fallback font.
 However, we recommend using a single fallback font, if possible, as shown here:
 
-[source,yaml]
+[,yaml]
 ----
 font:
   catalog:
@@ -68,7 +68,7 @@ TIP: If you are using more than one fallback font, add additional lines to the `
 
 Of course, make sure you've configured your theme to use your custom font:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-family: Roboto
@@ -81,7 +81,7 @@ You don't need to reference the fallback font anywhere else in your theme file.
 
 Here's another example that shows how to use an alternative emoji font (Symbola):
 
-[source,yaml]
+[,yaml]
 ----
 extends: default-with-fallback-font
 font:
diff --git a/docs/modules/theme/pages/font.adoc b/docs/modules/theme/pages/font.adoc
index 1f61fe0b..d6123cdd 100644
--- a/docs/modules/theme/pages/font.adoc
+++ b/docs/modules/theme/pages/font.adoc
@@ -1,10 +1,11 @@
 = Font Category Keys
+:description: Reference list of the available font category keys and their value types.
 :navtitle: Font
 :source-language: yaml
 
 == font
 
-The font key is where you declare custom fonts (`catalog` key) and configure the fallback fonts (`fallbacks` key).
+The `font` category key is where you declare custom fonts (`catalog` key) and configure the fallback fonts (`fallbacks` key).
 
 The data format of the `catalog` key is a map.
 Each key is the name of the font that you can use to refer to the font elsewhere in the theme.
@@ -46,7 +47,7 @@ font:
 If you define a xref:custom-font.adoc[custom font] in the font catalog in a theme that extends from `default`, and you want to continue to use the bundled fonts in your theme, you either have to redeclare the bundled fonts:
 
 .Redeclaring the bundle fonts in a custom theme
-[source,yaml]
+[,yaml]
 ----
 extends: default
 font:
@@ -70,7 +71,7 @@ heading:
 or you need to set `merge: true` above your font definitions:
 
 .Merging with the inherited font catalog
-[source,yaml]
+[,yaml]
 ----
 extends: default
 font:
diff --git a/docs/modules/theme/pages/footnotes.adoc b/docs/modules/theme/pages/footnotes.adoc
index 239e8d2c..c6f018c5 100644
--- a/docs/modules/theme/pages/footnotes.adoc
+++ b/docs/modules/theme/pages/footnotes.adoc
@@ -1,8 +1,9 @@
 = Footnotes Category Keys
+:description: Reference list of the available footnotes category keys and their value types.
 :navtitle: Footnotes
 :source-language: yaml
 
-The keys in the `footnotes` category control the style of the footnotes list at the end of a chapter (book doctype) or document (other doctypes).
+The keys in the `footnotes` category control the style of the footnotes list at the end of a chapter (`book` doctype) or document (other doctypes).
 If the `footnotes-title` attribute is specified in a document, it's styled as a xref:caption.adoc[block caption].
 The styling of the links is controlled by the xref:link.adoc[global link styles].
 
@@ -15,7 +16,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] +
diff --git a/docs/modules/theme/pages/heading.adoc b/docs/modules/theme/pages/heading.adoc
index f5b93d71..5a394149 100644
--- a/docs/modules/theme/pages/heading.adoc
+++ b/docs/modules/theme/pages/heading.adoc
@@ -1,4 +1,5 @@
 = Heading Category Keys
+:description: Reference list of the available heading category keys and their value types.
 :navtitle: Heading
 :source-language: yaml
 
@@ -26,7 +27,7 @@ heading:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 heading:
@@ -93,7 +94,7 @@ heading:
 (default: `$heading-font-color`)
 |[source]
 heading:
-  text-decoration-color: #cccccc
+  text-decoration-color: #CCCCCC
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -159,7 +160,7 @@ heading:
   h4-font-family: Roboto
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: `$heading-font-kerning`)
 |[source]
 heading:
@@ -200,12 +201,12 @@ heading:
 heading:
   h2-margin-top: 6
 
-|padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|<<padding,padding>>
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: _not set_)
 |[source]
 heading:
-  h2-padding: [0 0, 6]
+  h2-padding: [0, 2, 0, 6]
 
 |text-align
 |xref:text.adoc#text-align[Text alignment] +
@@ -243,6 +244,9 @@ heading:
   h3-text-transform: uppercase
 |===
 
+[#padding]
+=== padding
+
 The `padding` key is only intended to be used to offset the border by a fixed amount.
 If you want to put spacing around the top and bottom edges of the heading container, you should use the `margin-*` keys instead.
 
@@ -281,19 +285,19 @@ The doctype must be `book` for the `heading-part` keys to take effect.
 |===
 |Key |Value Type |Example
 
-|part-break-before
+|`part-break-after`
 |`always` {vbar} `auto` +
-(default: `always`)
+(default: `auto`)
 |[source]
 heading:
   part:
-    break-before: auto
+    break-after: always
 
-|`part-break-after`
+|part-break-before
 |`always` {vbar} `auto` +
-(default: `auto`)
+(default: `always`)
 |[source]
 heading:
   part:
-    break-after: always
+    break-before: auto
 |===
diff --git a/docs/modules/theme/pages/index-section.adoc b/docs/modules/theme/pages/index-section.adoc
index 59993518..b669a3b9 100644
--- a/docs/modules/theme/pages/index-section.adoc
+++ b/docs/modules/theme/pages/index-section.adoc
@@ -1,19 +1,20 @@
 = Index Category Key
+:description: Reference list of the available index category keys and their value types.
 :navtitle: Index
 :source-language: yaml
 
-The key in the `index` category controls the number of columns in the autogenerated index section.
+The keys in the `index` category control the spacing and number of columns in the autogenerated index section.
 
 [cols="4,4,6a"]
 |===
 |Key |Value Type |Example
 
-|column_gap
+|column-gap
 |xref:measurement-units.adoc[Measurement] +
 (default: `$base-font-size`)
 |[source]
 index:
-  column_gap: 12
+  column-gap: 12
 
 |columns
 |Integer +
diff --git a/docs/modules/theme/pages/keyboard.adoc b/docs/modules/theme/pages/keyboard.adoc
index b201702c..09cd3e73 100644
--- a/docs/modules/theme/pages/keyboard.adoc
+++ b/docs/modules/theme/pages/keyboard.adoc
@@ -1,4 +1,5 @@
 = Keyboard Macro Category Keys
+:description: Reference list of the available keyboard UI macro (kbd) category keys and their value types.
 :navtitle: Keyboard
 :source-language: yaml
 
@@ -17,14 +18,14 @@ The kbd reference is a span of text denoting textual user input from a keyboard,
 (default: _not set_)
 |[source]
 kbd:
-  background-color: #fafafa
+  background-color: #FAFAFA
 
 |<<border-color,border-color>>
 |xref:color.adoc[Color] +
 (default: _not set_)
 |[source]
 kbd:
-  border-color: #cccccc
+  border-color: #CCCCCC
 
 |<<offset,border-offset>>
 |xref:language.adoc#values[Number] +
diff --git a/docs/modules/theme/pages/link.adoc b/docs/modules/theme/pages/link.adoc
index 9a042226..3081465f 100644
--- a/docs/modules/theme/pages/link.adoc
+++ b/docs/modules/theme/pages/link.adoc
@@ -1,4 +1,5 @@
 = Link Category Keys
+:description: Reference list of the available link category keys and their value types.
 :navtitle: Link
 :source-language: yaml
 
@@ -13,7 +14,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] +
@@ -27,7 +28,7 @@ link:
 (default: `'0000EE'`)
 |[source]
 link:
-  font-color: #428bca
+  font-color: #428BCA
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -62,7 +63,7 @@ link:
 (default: `$link-font-color`)
 |[source]
 link:
-  text-decoration-color: #0000ff
+  text-decoration-color: #0000FF
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
diff --git a/docs/modules/theme/pages/list.adoc b/docs/modules/theme/pages/list.adoc
index d182858d..4ed51d77 100644
--- a/docs/modules/theme/pages/list.adoc
+++ b/docs/modules/theme/pages/list.adoc
@@ -1,4 +1,5 @@
 = List Category Keys
+:description: Reference list of the available list category keys and their value types. The list category controls the styles of ordered and unordered lists.
 :navtitle: List
 :source-language: yaml
 
@@ -7,6 +8,9 @@
 
 The keys in the `list` category control the arrangement and style of ordered and unordered lists.
 
+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.
+The `text-align` key controls the alignment of the list text only, not nested content, such as nested blocks and lists.
+
 [cols="3,3,6a"]
 |===
 |Key |Value Type |Example
@@ -30,7 +34,7 @@ list:
 (default: _inherit_)
 |[source]
 list:
-  marker-font-color: #3c763d
+  marker-font-color: #3C763D
 
 |text-align
 |xref:text.adoc#text-align[Text alignment] +
@@ -40,9 +44,6 @@ list:
   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.
-The `text-align` key controls the alignment of the list text only, not nested content, such as nested blocks and lists.
-
 [#ulist-marker]
 == ulist-marker
 
@@ -74,7 +75,7 @@ ulist:
 |[source]
 ulist:
   marker:
-    font-color: #cccccc
+    font-color: #CCCCCC
 
 |line-height
 |xref:language.adoc#values[Number] +
@@ -128,7 +129,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 5157113a..211dd9b3 100644
--- a/docs/modules/theme/pages/mark.adoc
+++ b/docs/modules/theme/pages/mark.adoc
@@ -1,4 +1,5 @@
 = Mark Category Keys
+:description: Reference list of the available inline mark phrase category keys and their value types.
 :navtitle: Mark
 :source-language: yaml
 
@@ -13,7 +14,7 @@ The keys in the `mark` category apply to an inline mark phrase.
 (default: `'FFFF00'`)
 |[source]
 mark:
-  background-color: #fcf8e3
+  background-color: #FCF8E3
 
 |border-offset
 |xref:language.adoc#values[Number] +
diff --git a/docs/modules/theme/pages/math-operations.adoc b/docs/modules/theme/pages/math-operations.adoc
index 0d65054f..70d06d1d 100644
--- a/docs/modules/theme/pages/math-operations.adoc
+++ b/docs/modules/theme/pages/math-operations.adoc
@@ -1,6 +1,7 @@
 = Math Operations
+:description: The theming language supports basic math operations and rounding functions to calculate key values.
 
-The theme language supports basic math operations to support calculated values.
+The theme language supports basic math operations to calculate key values.
 
 == Operators
 
@@ -29,7 +30,7 @@ Like programming languages, the multiply and divide operators take precedence ov
 
 Here's an example of a math expression with fixed values.
 
-[source,yaml]
+[,yaml]
 ----
 conum:
   line-height: 4 / 3
@@ -39,7 +40,7 @@ IMPORTANT: Operators must always be surrounded by a space on either side (e.g.,
 
 Variables may be used in place of numbers anywhere in the expression:
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-size: 12
@@ -62,7 +63,7 @@ ceil(...):: Rounds the number down the previous integer.
 
 You might use these functions in font size calculations so that you get more exact values.
 
-[source,yaml]
+[,yaml]
 ----
 base:
   font-size: 12.5
diff --git a/docs/modules/theme/pages/measurement-units.adoc b/docs/modules/theme/pages/measurement-units.adoc
index 283fc57f..3bf35798 100644
--- a/docs/modules/theme/pages/measurement-units.adoc
+++ b/docs/modules/theme/pages/measurement-units.adoc
@@ -1,15 +1,17 @@
 = Measurement Units
 
 The default unit of measure for a PDF canvas is points (pt).
-However, humans like to think in units such as inches (in), centimeters (cm), or millimeters (mm).
-You can let the theme do this conversion for you automatically by adding a unit notation next to any number.
+However, you may prefer think of measurements in terms of inches (in), centimeters (cm), or millimeters (mm).
+The theme can convert from any of the supported measurement units to points when you specify a unit notation directly after a number.
 
+[#default]
 == Default unit
 
-Several of the keys require a value in points (pt), the unit of measure for the PDF canvas.
+Many of the theme keys, such as `border-width`, `padding`, etc., require their values be a measurement.
+If you specify a number without any units, the units defaults to points (pt), the unit of measure for the PDF canvas.
 A point is defined as 1/72 of an inch.
-If you specify a number without any units, the units defaults to pt.
 
+[#supported]
 == Supported units
 
 The following units are supported:
@@ -40,6 +42,7 @@ Currently, percentage units can only be used for placing elements on the title p
 |Default unit of measure when no unit is specified.
 |===
 
+[#specify]
 == Specify a measurement unit
 
 Here's an example of how you can use inches to define the page margins:
diff --git a/docs/modules/theme/pages/menu.adoc b/docs/modules/theme/pages/menu.adoc
index 1b2667a3..a70514b3 100644
--- a/docs/modules/theme/pages/menu.adoc
+++ b/docs/modules/theme/pages/menu.adoc
@@ -1,4 +1,5 @@
 = Menu Macro Category Keys
+:description: Reference list of the available menu UI macro category keys and their value types.
 :navtitle: Menu
 :source-language: yaml
 
diff --git a/docs/modules/theme/pages/page-numbers.adoc b/docs/modules/theme/pages/page-numbers.adoc
index 936c5d7d..638536d3 100644
--- a/docs/modules/theme/pages/page-numbers.adoc
+++ b/docs/modules/theme/pages/page-numbers.adoc
@@ -103,7 +103,7 @@ To learn more about customizing the running content, see xref:add-running-conten
 If you're not extending one of the built-in themes and starting with a blank theme, you can add the page number to the running content by using the `\{page-number}` attribute reference in the `content` key.
 
 .Add page number to footer in blank theme
-[source,yaml]
+[,yaml]
 ----
 footer:
   recto:
diff --git a/docs/modules/theme/pages/prepare-custom-font.adoc b/docs/modules/theme/pages/prepare-custom-font.adoc
index 600401a6..6f84a875 100644
--- a/docs/modules/theme/pages/prepare-custom-font.adoc
+++ b/docs/modules/theme/pages/prepare-custom-font.adoc
@@ -14,7 +14,7 @@ Before using the font, you may want to check that the font is valid.
 To do so, create the following script, which will verify that the font is free from errors.
 
 .validate-font.rb
-[source,ruby]
+[,ruby]
 ----
 require 'ttfunk'
 require 'ttfunk/subset_collection'
@@ -38,7 +38,7 @@ Resaving the font in FontForge will usually resolve any errors in the font.
 == Modifying the font
 
 To ready your font for use with Asciidoctor PDF, you'll need to modify it using a font program.
-We recommend using {url-fontforge}[FontForge].
+We recommend using {url-fontforge}[FontForge^].
 But don't let this scare you off.
 FontForge essentially works like a vector-drawing tool, in which each character is a separate canvas.
 You can find a crash course in how to use the program on the FontForge project site.
diff --git a/docs/modules/theme/pages/prose.adoc b/docs/modules/theme/pages/prose.adoc
index f000a12d..af6e6ee6 100644
--- a/docs/modules/theme/pages/prose.adoc
+++ b/docs/modules/theme/pages/prose.adoc
@@ -1,4 +1,5 @@
 = Prose Category Keys
+:description: Reference list of the available prose category keys and their value types.
 :navtitle: Prose
 :source-language: yaml
 
diff --git a/docs/modules/theme/pages/quote.adoc b/docs/modules/theme/pages/quote.adoc
index 1ce788c2..e719906c 100644
--- a/docs/modules/theme/pages/quote.adoc
+++ b/docs/modules/theme/pages/quote.adoc
@@ -1,4 +1,5 @@
 = Quote Category Keys
+:description: Reference list of the available quote block category keys and their value types.
 :navtitle: Quote
 :source-language: yaml
 
@@ -23,7 +24,7 @@ quote:
 (default: `'EEEEEE'`)
 |[source]
 quote:
-  border-color: #e6e8fa
+  border-color: #E6E8fA
 
 |<<border-width,border-left-width>>
 |xref:blocks.adoc#border-width[Measurement] +
@@ -68,7 +69,7 @@ quote:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 quote:
@@ -89,7 +90,7 @@ quote:
   font-style: bold
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `[3, 12, 3, 14]`)
 |[source]
 quote:
@@ -143,7 +144,7 @@ quote:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 quote:
@@ -164,6 +165,6 @@ quote:
 |[source]
 quote:
   cite:
-    text-transform: uppercase
+    text-transform: smallcaps
 |===
 
diff --git a/docs/modules/theme/pages/quoted-string.adoc b/docs/modules/theme/pages/quoted-string.adoc
index 506426da..4868c7da 100644
--- a/docs/modules/theme/pages/quoted-string.adoc
+++ b/docs/modules/theme/pages/quoted-string.adoc
@@ -1,10 +1,11 @@
 = Quoted String
+:url-yaml-strings: https://symfony.com/doc/current/components/yaml/yaml_format.html#strings
 
 Some keys accept a quoted string as text content.
 The final segment of these keys is always named `content`.
 
 A content key accepts a string value.
-It's usually best to quote the string or use the http://symfony.com/doc/current/components/yaml/yaml_format.html#strings[YAML multi-line string syntax].
+It's usually best to quote the string or use the {url-yaml-strings}[YAML multi-line string syntax^].
 
 Text content may be formatted using a subset of inline HTML.
 You can use the well-known elements such as `<strong>`, `<em>`, `<code>`, `<a>`, `<sub>`, `<sup>`, `<del>`, and `<span>`.
diff --git a/docs/modules/theme/pages/quotes.adoc b/docs/modules/theme/pages/quotes.adoc
index d6718c3a..42aa5066 100644
--- a/docs/modules/theme/pages/quotes.adoc
+++ b/docs/modules/theme/pages/quotes.adoc
@@ -1,4 +1,5 @@
 = Quotes Category Keys
+:description: Reference list of the available quotes category key and its value type. The quotes key defines the typographic quotation mark characters.
 :navtitle: Quotes
 :source-language: yaml
 
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index bcabcca9..98f49a05 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -31,7 +31,7 @@ role:
 |[source]
 role:
   found:
-    border-color: #cccccc
+    border-color: #CCCCCC
 
 |border-offset
 |xref:language.adoc#values[Number] +
@@ -63,7 +63,7 @@ role:
 |[source]
 role:
   red:
-    font-color: #ff0000
+    font-color: #FF0000
 
 |font-family
 |xref:font-support.adoc[Font family name] +
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc
index 7fe445be..696dd040 100644
--- a/docs/modules/theme/pages/running-content.adoc
+++ b/docs/modules/theme/pages/running-content.adoc
@@ -1,4 +1,5 @@
 = Running Content Category Keys
+:description: Reference list of the available running content, header, and footer category keys and their value types.
 :navtitle: Running Content
 :source-language: yaml
 :conum-guard-yaml: #
@@ -21,7 +22,7 @@ IMPORTANT: If you don't specify a `height` for the header, it effectively disabl
 (default: _not set_)
 |[source]
 header:
-  background-color: #eeeeee
+  background-color: #EEEEEE
 
 |background-image
 |xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
@@ -35,7 +36,7 @@ header:
 (default: _not set_)
 |[source]
 header:
-  border-color: #dddddd
+  border-color: #DDDDDD
 
 |border-style
 |xref:blocks.adoc#border-style[Border style] +
@@ -108,7 +109,7 @@ header:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 header:
@@ -136,7 +137,7 @@ header:
   height: 0.75in
 
 |image-vertical-align
-|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] +
+|`bottom` {vbar} `middle` {vbar} `top` {vbar} xref:measurement-units.adoc[Measurement] +
 (default: _not set_)
 |[source]
 header:
@@ -249,7 +250,7 @@ IMPORTANT: If you don't specify a `height` for the footer, it effectively disabl
 (default: _not set_)
 |[source]
 footer:
-  background-color: #eeeeee
+  background-color: #EEEEEE
 
 |background-image
 |xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
@@ -263,7 +264,7 @@ footer:
 (default: _not set_)
 |[source]
 footer:
-  border-color: #dddddd
+  border-color: #DDDDDD
 
 |border-style
 |xref:blocks.adoc#border-style[Border style] +
@@ -336,7 +337,7 @@ footer:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 footer:
@@ -364,7 +365,7 @@ footer:
   height: 0.75in
 
 |image-vertical-align
-|`top` {vbar} `middle` {vbar} `bottom` {vbar} xref:measurement-units.adoc[Measurement] +
+|`bottom` {vbar} `middle` {vbar} `top` {vbar} xref:measurement-units.adoc[Measurement] +
 (default: _not set_)
 |[source]
 footer:
diff --git a/docs/modules/theme/pages/section.adoc b/docs/modules/theme/pages/section.adoc
index 95d3f8de..72e1379b 100644
--- a/docs/modules/theme/pages/section.adoc
+++ b/docs/modules/theme/pages/section.adoc
@@ -1,9 +1,14 @@
 = Section Category Key
+:description: Reference list of the available section category key and its value types.
 :navtitle: Section
 :source-language: yaml
 
 The key in the `section` category controls the indent of a section body.
 
+The `indent` keys applies to the section body only, excluding section titles and discrete headings.
+A single value gets applied to both the left and right side (e.g., `0.5in`).
+A two-value array configures the left and right side independently (e.g., `[0.5in, 0]`).
+
 [cols="3,6,4a"]
 |===
 |Key |Value Type |Example
@@ -15,7 +20,3 @@ The key in the `section` category controls the indent of a section body.
 section:
   indent: [0.5in, 0]
 |===
-
-The `indent` keys applies to the section body only, excluding section titles and discrete headings.
-A single value gets applied to both the left and right side (e.g., `0.5in`).
-A two-value array configures the left and right side independently (e.g., `[0.5in, 0]`).
diff --git a/docs/modules/theme/pages/sidebar.adoc b/docs/modules/theme/pages/sidebar.adoc
index 3e4b3e55..0f517762 100644
--- a/docs/modules/theme/pages/sidebar.adoc
+++ b/docs/modules/theme/pages/sidebar.adoc
@@ -1,4 +1,5 @@
 = Sidebar Category Keys
+:description: Reference list of the available sidebar category keys and their value types.
 :navtitle: Sidebar
 :source-language: yaml
 
@@ -23,7 +24,7 @@ sidebar:
 (default: _not set_)
 |[source]
 sidebar:
-  border-color: #ffffff
+  border-color: #FFFFFF
 
 |border-radius
 |xref:blocks.adoc#radius[Measurement] +
@@ -61,7 +62,7 @@ sidebar:
   font-family: M+ 1p
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 sidebar:
@@ -82,18 +83,18 @@ sidebar:
   font-style: italic
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `12`)
 |[source]
 sidebar:
-  padding: [12, 15, 0, 15]
+  padding: [12, 15]
 
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: _inherit_)
 |[source]
 sidebar:
-  text-transform: uppercase
+  text-transform: none
 |===
 
 [#title]
@@ -122,7 +123,7 @@ sidebar:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 sidebar:
@@ -159,5 +160,5 @@ sidebar:
 |[source]
 sidebar:
   title:
-    text-transform: capitalize
+    text-transform: smallcaps
 |===
diff --git a/docs/modules/theme/pages/source-highlighting-theme.adoc b/docs/modules/theme/pages/source-highlighting-theme.adoc
index 5b9f7304..0aefee37 100644
--- a/docs/modules/theme/pages/source-highlighting-theme.adoc
+++ b/docs/modules/theme/pages/source-highlighting-theme.adoc
@@ -1,4 +1,7 @@
 = Source Highlighting Themes
+:url-jneen-rouge: https://github.com/jneen/rouge
+:url-ruby-rouge-themes: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
+:url-rouge-project: https://rouge.jneen.net/
 
 You can apply a bundled source highlighter theme to your source blocks or define and apply your own.
 
@@ -10,8 +13,9 @@ Then, specify the desired theme using the `rouge-style` document attribute.
 
 The following example demonstrates how to apply the monokai theme from Rouge to source blocks.
 
-[source,asciidoc]
+[,asciidoc]
 ----
+= Document Title
 :source-highlighter: rouge
 :rouge-style: monokai
 ----
@@ -20,7 +24,7 @@ You can generate a list of all available themes by running the following command
 
  $ ruby -e 'require :rouge.to_s; puts Rouge::Theme.registry.keys.sort.join ?\n'
 
-You can also find the list of themes in the Rouge source repository at https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes.
+You can also find the {url-ruby-rouge-themes}[list of themes in the Rouge source repository].
 
 If the bundled themes don't suit your needs, you can define one of your own.
 
@@ -32,7 +36,7 @@ Name the file according to the name of your theme and put the file in a folder o
 The name of the Ruby class doesn't matter, though it's customary to name it according to the name of the theme as well.
 
 .rouge_themes/custom.rb
-[source,ruby]
+[,ruby]
 ----
 require 'rouge' unless defined? ::Rouge.version
 
@@ -70,13 +74,14 @@ Colors are defined using hexadecimal format (e.g., #ff0000 for red).
 
 Use the `Text` token to set the background color of the source block and the default text color.
 
-The complete list of tokens can be found in the https://github.com/jneen/rouge/blob/master/lib/rouge/token.rb[token.rb] file from Rouge.
-Refer to the https://github.com/jneen/rouge/tree/master/lib/rouge/themes[bundled themes] to find more examples.
+The complete list of tokens can be found in the {url-jneen-rouge}/blob/master/lib/rouge/token.rb[token.rb file^] from Rouge.
+Refer to the {url-jneen-rouge}/tree/master/lib/rouge/themes[bundled themes^] to find more examples.
 
 Once you've defined your theme, you need to enable it use it using the `rouge-style` document attribute, which you specify in the document header or via the Asciidoctor CLI or API.
 
-[source,asciidoc]
+[,asciidoc]
 ----
+= Document Title
 :source-highlighter: rouge
 :rouge-style: custom
 ----
@@ -86,4 +91,4 @@ Finally, you need to activate your theme by requiring the theme file when you in
  $ asciidoctor -r ./rouge_themes/custom.rb sample.adoc
 
 You should now see that the source code is highlighted to your liking.
-For more information about source highlighting with Rouge, refer to the https://rouge.jneen.net/[Rouge project page].
+For more information about source highlighting with Rouge, refer to the {url-rouge-project}[Rouge project page^].
diff --git a/docs/modules/theme/pages/svg.adoc b/docs/modules/theme/pages/svg.adoc
index 4831a127..e613d6fa 100644
--- a/docs/modules/theme/pages/svg.adoc
+++ b/docs/modules/theme/pages/svg.adoc
@@ -1,19 +1,19 @@
 = SVG Category Key
+:description: Reference list of the available svg category key and its value type.
 :navtitle: SVG
 :source-language: yaml
 
 The key in the `svg` category controls the SVG fallback font.
+The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
 
 [cols="4,4,6a"]
 |===
 |Key |Value Type |Example
 
-|fallback_font_family
+|fallback-font-family
 |xref:font-support.adoc[Font family name] +
 (default: `$base-font-family`)
 |[source]
 svg:
-  fallback_font_family: Times-Roman
+  fallback-font-family: Times-Roman
 |===
-
-The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
diff --git a/docs/modules/theme/pages/table.adoc b/docs/modules/theme/pages/table.adoc
index 8f4fd2de..00854f09 100644
--- a/docs/modules/theme/pages/table.adoc
+++ b/docs/modules/theme/pages/table.adoc
@@ -27,21 +27,21 @@ table:
   background-color: #FFFFFF
 
 |border-color
-|xref:tables.adoc#border-color[Color] {vbar} xref:tables.adoc#border-color[Color[ \]] +
+|xref:tables.adoc#border-color[Color] {vbar} xref:tables.adoc#border-color[Color[\]] +
 (default: `'000000'`)
 |[source]
 table:
   border-color: #DDDDDD
 
 |border-style
-|xref:tables.adoc#border-style[Border style] {vbar} xref:tables.adoc#border-style[Border style[ \]] +
+|xref:tables.adoc#border-style[Border style] {vbar} xref:tables.adoc#border-style[Border style[\]] +
 (default: `solid`)
 |[source]
 table:
   border-style: [solid, ~, solid, dotted]
 
 |border-width
-|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[ \]] +
+|xref:blocks.adoc#border-width[Measurement] {vbar} xref:blocks.adoc#border-width[Measurement[\]] +
 (default: `0.5`)
 |[source]
 table:
@@ -62,7 +62,7 @@ table:
   font-family: Helvetica
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 table:
@@ -83,21 +83,21 @@ table:
   font-style: italic
 
 |grid-color
-|xref:tables.adoc#grid-color[Color] {vbar} xref:tables.adoc#grid-color[Color[ \]] +
+|xref:tables.adoc#grid-color[Color] {vbar} xref:tables.adoc#grid-color[Color[\]] +
 (default: `$table-border-color`)
 |[source]
 table:
   grid-color: #EEEEEE
 
 |grid-style
-|xref:tables.adoc#grid-style[Grid style] {vbar} xref:tables.adoc#grid-style[Grid style[ \]] +
+|xref:tables.adoc#grid-style[Grid style] {vbar} xref:tables.adoc#grid-style[Grid style[\]] +
 (default: `$table-border-style`)
 |[source]
 table:
   grid-style: dashed
 
 |grid-width
-|xref:tables.adoc#grid-width[Measurement] {vbar} xref:tables.adoc#grid-width[Measurement[ \]] +
+|xref:tables.adoc#grid-width[Measurement] {vbar} xref:tables.adoc#grid-width[Measurement[\]] +
 (default: `$table-border-width`)
 |[source]
 table:
@@ -147,7 +147,7 @@ table:
     border-bottom-width: 1
 
 |cell-padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `$table-cell-padding`)
 |[source]
 table:
@@ -171,7 +171,7 @@ table:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 table:
@@ -305,7 +305,7 @@ table:
     line-height: 1.5
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `2`)
 |[source]
 table:
@@ -400,16 +400,16 @@ The keys listed on xref:caption.adoc[] can also be nested under the `table-capti
 |===
 |Key |Value Type |Example
 
-|caption-align
-|xref:blocks.adoc#align[Block alignment] {vbar} xref:tables.adoc#caption-align[inherit] +
+|xref:tables.adoc#caption-align[caption-align]
+|xref:tables.adoc#caption-align[Block alignment] {vbar} xref:tables.adoc#caption-align[inherit] +
 (default: `$caption-align`)
 |[source]
 table:
   caption:
     align: center
 
-|caption-end
-|xref:tables.adoc#end[bottom] {vbar} xref:tables.adoc#end[top] +
+|xref:tables.adoc#end[caption-end]
+|xref:tables.adoc#end[End placement] +
 (default: `top`)
 |[source]
 table:
@@ -424,11 +424,13 @@ table:
   caption:
     max-width: none
 
-|caption-text-align
-|xref:text.adoc#text-align[Text alignment] {vbar} xref:tables.adoc#caption-text-align[inherit] +
+|xref:tables.adoc#caption-text-align[caption-text-align]
+|xref:tables.adoc#caption-text-align[Text alignment] {vbar} xref:tables.adoc#caption-text-align[inherit] +
 (default: `$table-caption-align`)
 |[source]
 table:
   caption:
-    text-align: left
+    text-align: center
 |===
+
+For more information about styling tables using the theming language, see xref:tables.adoc[].
diff --git a/docs/modules/theme/pages/tables.adoc b/docs/modules/theme/pages/tables.adoc
index dbdab2a6..c37716e2 100644
--- a/docs/modules/theme/pages/tables.adoc
+++ b/docs/modules/theme/pages/tables.adoc
@@ -160,7 +160,7 @@ See xref:table.adoc#body[the table-body category] for a list of all theme keys t
 [#caption-align]
 == Caption alignment
 
-In addition to the `center`, `left`, and `right` block alignment keywords, the `caption-align` key accepts the value `inherit`.
+In addition to the xref:blocks.adoc#align[center, left, and right block alignment keywords], the `caption-align` key accepts the value `inherit` when set on the `table` category.
 
 [,yaml]
 ----
@@ -169,12 +169,15 @@ table:
     align: inherit
 ----
 
-The value `inherit` resolves to the block alignment (`table-align`) assigned to the `table` category.
+When the value is `inherit`, the `table-caption-align` key will inherit the alignment assigned to the table itself (`table-align`).
+The `caption-align` key is distinct from the similarly-named `caption-text-align` key.
+The <<caption-text-align,caption-text-align key>> aligns text within the text box of the caption block using text alignment rules.
 
 [#caption-text-align]
 == Caption text alignment
 
-The `caption-text-align` key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `table` category.
+The `caption-text-align` key controls the alignment of the caption text within the bounds of the table caption.
+The key accepts the keyword `inherit` as well as the xref:text.adoc#text-align[usual text alignment values] when set on the `table` category.
 
 [,yaml]
 ----
@@ -183,7 +186,10 @@ table:
     text-align: inherit
 ----
 
-The value `inherit` resolves to the block alignment (`table-align`) assigned to the `table` category.
+The value `inherit` resolves to the alignment assigned to the table itself (`table-align`).
+
+The `caption-text-align` key is distinct from the similarly-named `caption-align` key.
+The <<caption-align,caption-align key>> aligns a caption block horizontally within its container.
 
 [#end]
 == Caption end
diff --git a/docs/modules/theme/pages/text.adoc b/docs/modules/theme/pages/text.adoc
index 533a964b..278081ae 100644
--- a/docs/modules/theme/pages/text.adoc
+++ b/docs/modules/theme/pages/text.adoc
@@ -1,45 +1,34 @@
 = Text Styles
+:description: The theming language provides keys for aligning, decorating, styling, and transforming text.
 
 [#text-align]
 == Text alignment
 
 The `text-align` key is used to align text horizontally within the text box.
 It has the same function as the `text-align` property in CSS.
-
 The text can be aligned using the following keywords:
 
-`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.
+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.
+inherit:: *Only applies to the caption text of block images (`image-caption`) and tables (`table-caption`).*
+The value `inherit` resolves to the alignment of the block.
+Further information about using `inherit` on image caption text and table caption text can be found on xref xref:block-images.adoc#caption-text-align[Block Image Styles] and xref:tables.adoc#caption-text-align[Table Styles], respectively.
 
 The `text-align` key is distinct from the similarly-named `align` key.
 The xref:blocks.adoc#align[align key] aligns a block element horizontally within its container.
 
-[#caption-text-align]
-=== Caption text alignment
-
-In addition to the alignment keywords listed in the <<text-align>> section, the `caption-text-align` key accepts the keyword `inherit` when it is set on the `image` or `table` category.
-
-[,yaml]
-----
-image:
-  caption:
-    text-align: inherit
-----
-
-The value `inherit` resolves to the alignment of the block image or table.
-
 [#decoration]
 == Decoration
 
 The `text-decoration` key specifies the type of decoration, such as an underline, that is applied to the text.
 It accepts the following keywords:
 
-`line-through`:: A line is drawn across the text.
+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.
+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.
 
@@ -49,11 +38,11 @@ When a key category allows the `text-decoration` key to be set, you can usually
 The `font-style` key specifies the font variant in a font family that the text should use.
 The key accepts the following keywords:
 
-`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.
+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.
 
 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.
@@ -64,10 +53,10 @@ The converter uses the values of both keys in combination to locate the correct
 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.
-`smallcaps`:: Replaces lowercase Latin letters with their small capital variant.
+capitalize:: Transforms the first letter of each word to a capital letter.
+lowercase:: Transforms all the text to lower case letters.
+none:: Clears an inherited value and no case transformation is applied to the text.
+smallcaps:: Replaces lowercase Latin letters with their small capital variant.
+uppercase:: Transforms all the text to capital letters.
 
 The `text-transform` key can’t be set on the xref:base.adoc[base category].
diff --git a/docs/modules/theme/pages/thematic-break.adoc b/docs/modules/theme/pages/thematic-break.adoc
index b6a170de..18fdb5a0 100644
--- a/docs/modules/theme/pages/thematic-break.adoc
+++ b/docs/modules/theme/pages/thematic-break.adoc
@@ -1,4 +1,5 @@
 = Thematic Break Category Keys
+:description: Reference list of the available thematic break category keys and their value types.
 :navtitle: Thematic Break
 :source-language: yaml
 
@@ -13,7 +14,7 @@ The keys in the `thematic-break` category control the style of thematic breaks,
 (default: `'EEEEEE'`)
 |[source]
 thematic-break:
-  border-color: #e6e8fa
+  border-color: #E6E8FA
 
 |border-style
 |`dashed` {vbar} `dotted` {vbar} `double` {vbar} `solid` +
diff --git a/docs/modules/theme/pages/title-page.adoc b/docs/modules/theme/pages/title-page.adoc
index 1a58b4ca..84be5ce5 100644
--- a/docs/modules/theme/pages/title-page.adoc
+++ b/docs/modules/theme/pages/title-page.adoc
@@ -42,7 +42,7 @@ title-page:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 title-page:
@@ -163,7 +163,7 @@ title-page:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 title-page:
@@ -216,7 +216,7 @@ title-page:
 |[source]
 title-page:
   title:
-    text-transform: uppercase
+    text-transform: smallcaps
 
 |<<top,top>>
 |xref:measurement-units.adoc[Measurement] +
@@ -262,7 +262,7 @@ title-page:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 title-page:
@@ -371,7 +371,7 @@ title-page:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 title-page:
@@ -466,7 +466,7 @@ title-page:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 title-page:
@@ -511,5 +511,5 @@ title-page:
 |[source]
 title-page:
   revision:
-    text-transform: uppercase
+    text-transform: none
 |===
diff --git a/docs/modules/theme/pages/toc.adoc b/docs/modules/theme/pages/toc.adoc
index f174bbdb..7de11539 100644
--- a/docs/modules/theme/pages/toc.adoc
+++ b/docs/modules/theme/pages/toc.adoc
@@ -1,4 +1,5 @@
 = Table of Contents Category Keys
+:description: Reference list of the available TOC category keys and their value types.
 :navtitle: TOC
 :source-language: yaml
 
@@ -26,7 +27,7 @@ toc:
   font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 toc:
@@ -87,7 +88,7 @@ toc:
 (default: `$toc-font-color`)
 |[source]
 toc:
-  text-decoration-color: #cccccc
+  text-decoration-color: #CCCCCC
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -129,7 +130,7 @@ toc:
   h2-font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 toc:
@@ -154,7 +155,7 @@ toc:
 (default: _inherit_)
 |[source]
 toc:
-  h3-text-transform: uppercase
+  h3-text-transform: none
 |===
 
 [#title]
@@ -172,7 +173,7 @@ The keys in the `toc-title` category control the arrangement and style of the ti
 |[source]
 toc:
   title:
-    font-color: #aa0000
+    font-color: #AA0000
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -183,7 +184,7 @@ toc:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 toc:
diff --git a/docs/modules/theme/pages/variables.adoc b/docs/modules/theme/pages/variables.adoc
index f8253503..fc289707 100644
--- a/docs/modules/theme/pages/variables.adoc
+++ b/docs/modules/theme/pages/variables.adoc
@@ -1,4 +1,5 @@
 = Variables
+:description: The theming language supports variables.
 :conum-guard-yaml: #
 
 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.
diff --git a/docs/modules/theme/pages/verse.adoc b/docs/modules/theme/pages/verse.adoc
index 1b58486f..d6227d0b 100644
--- a/docs/modules/theme/pages/verse.adoc
+++ b/docs/modules/theme/pages/verse.adoc
@@ -1,4 +1,5 @@
 = Verse Category Keys
+:description: Reference list of the available verse block category keys and their value types.
 :navtitle: Verse
 :source-language: yaml
 
@@ -23,7 +24,7 @@ verse:
 (default: `'EEEEEE'`)
 |[source]
 verse:
-  border-color: #e6e8fa
+  border-color: #E6E8FA
 
 |<<border-width,border-left-width>>
 |xref:blocks.adoc#border-width[Measurement] +
@@ -68,7 +69,7 @@ verse:
   font-family: M+ 1mn
 
 |font-kerning
-|normal {vbar} none +
+|none {vbar} normal +
 (default: _inherit_)
 |[source]
 verse:
@@ -89,18 +90,18 @@ verse:
   font-style: bold
 
 |padding
-|xref:measurement-units.adoc[Measurement] {vbar} xref:measurement-units.adoc[Measurement[top,right,bottom,left\]] +
+|xref:blocks.adoc#padding[Measurement] {vbar} xref:blocks.adoc#padding[Measurement[\]] +
 (default: `[3, 12, 3, 14]`)
 |[source]
 verse:
-  padding: [3, 0, 3, 20]
+  padding: 3
 
 |text-transform
 |xref:text.adoc#transform[Text transform] +
 (default: _inherit_)
 |[source]
 verse:
-  text-transform: uppercase
+  text-transform: lowercase
 |===
 
 [#border-width]
@@ -141,7 +142,7 @@ verse:
     font-family: Noto Serif
 
 |font-kerning
-|`normal` {vbar} `none` +
+|`none` {vbar} `normal` +
 (default: _inherit_)
 |[source]
 verse: