resolves #2095 separate align and text-align keys in theme schema and update docs (PR #2096)

32 files changed, 188 insertions, 118 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 0152f029..994d9d29 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -9,6 +9,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/main[co
 
 Enhancements::
 
+* separate `align` and `text-align` keys in theme schema; remap old keys for backwards compatibility (#2095)
 * allow theme to control the border on all sides of tables independently (#902)
 * keep section title with first block of content is `breakable` option is set on section (#2075, #38)
 * pass `part`, `chapterlike`, and `hidden` options to `arrange_section` method
diff --git a/data/themes/base-theme.yml b/data/themes/base-theme.yml
index 6bdb0887..e187dd8b 100644
--- a/data/themes/base-theme.yml
+++ b/data/themes/base-theme.yml
@@ -7,7 +7,7 @@ page_margin: 36
 page_margin_inner: 48
 page_margin_outer: 24
 page_size: A4
-base_align: left
+base_text_align: left
 #base_font_color: '333333'
 base_font_color: '000000'
 #base_font_family: Times-Roman
@@ -46,7 +46,7 @@ heading_line_height: 1.15
 heading_margin_top: 4
 heading_margin_bottom: 12
 heading_min_height_after: 20
-title_page_align: center
+title_page_text_align: center
 title_page_line_height: 1.15
 title_page_logo_top: 10%
 title_page_title_top: 40%
diff --git a/data/themes/default-theme.yml b/data/themes/default-theme.yml
index 85ec3141..0df087c6 100644
--- a/data/themes/default-theme.yml
+++ b/data/themes/default-theme.yml
@@ -22,7 +22,7 @@ page:
   margin_outer: 0.59in
   size: A4
 base:
-  align: justify
+  text_align: justify
   # color as hex string (leading # is optional)
   font_color: 333333
   # color as RGB array
@@ -96,7 +96,7 @@ menu:
   caret_content: " <font size=\"1.15em\" color=\"#B12146\">\u203a</font> "
   font_style: bold
 heading:
-  align: left
+  text_align: left
   font_color: $base_font_color
   font_style: bold
   # h1 is used for part titles (book doctype) or the doctitle (article doctype)
@@ -114,7 +114,7 @@ heading:
   margin_bottom: $vertical_rhythm * 0.9
   min_height_after: $base_line_height_length * 1.5
 title_page:
-  align: right
+  text_align: right
   logo:
     top: 10%
   title:
@@ -148,7 +148,7 @@ abstract:
   font_style: italic
   first_line_font_style: bold
   title:
-    align: center
+    text_align: center
     font_color: $heading_font_color
     font_size: $heading_h4_font_size
     font_style: $heading_font_style
@@ -218,7 +218,7 @@ sidebar:
   border_width: $base_border_width
   padding: [$vertical_rhythm, $vertical_rhythm * 1.25, $vertical_rhythm, $vertical_rhythm * 1.25]
   title:
-    align: center
+    text_align: center
     font_color: $heading_font_color
     font_size: $heading_h4_font_size
     font_style: $heading_font_style
diff --git a/docs/modules/theme/nav.adoc b/docs/modules/theme/nav.adoc
index d4437e9a..712f31e3 100644
--- a/docs/modules/theme/nav.adoc
+++ b/docs/modules/theme/nav.adoc
@@ -1,6 +1,7 @@
 * xref:index.adoc[]
 ** xref:language.adoc[]
 *** xref:measurement-units.adoc[]
+*** xref:blocks.adoc[]
 *** xref:text.adoc[]
 *** xref:image.adoc[]
 *** xref:color.adoc[]
diff --git a/docs/modules/theme/pages/abstract.adoc b/docs/modules/theme/pages/abstract.adoc
index 9eda84d2..ad7c0696 100644
--- a/docs/modules/theme/pages/abstract.adoc
+++ b/docs/modules/theme/pages/abstract.adoc
@@ -89,13 +89,13 @@ The keys in the `abstract-title` category control the style and alignment of the
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
 (default: `center`)
 |[source]
 abstract:
   title:
-    align: center
+    text-align: center
 
 |font-color
 |xref:color.adoc[Color] +
diff --git a/docs/modules/theme/pages/admonition.adoc b/docs/modules/theme/pages/admonition.adoc
index 7a27b982..cab0587e 100644
--- a/docs/modules/theme/pages/admonition.adoc
+++ b/docs/modules/theme/pages/admonition.adoc
@@ -128,13 +128,13 @@ The keys in the `admonition-label` category control the arrangement and style of
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
 (default: `center`)
 |[source]
 admonition:
   label:
-    align: left
+    text-align: left
 
 |font-color
 |xref:color.adoc[Color] +
diff --git a/docs/modules/theme/pages/asciidoc-attributes.adoc b/docs/modules/theme/pages/asciidoc-attributes.adoc
index 5fc2f153..2a3d43b1 100644
--- a/docs/modules/theme/pages/asciidoc-attributes.adoc
+++ b/docs/modules/theme/pages/asciidoc-attributes.adoc
@@ -113,7 +113,7 @@ If an attribute matches a key in the theme file, the attribute takes precedence.
 |`:scripts: cjk`
 
 |`text-align`^[9]^
-|xref:text.adoc#align[Text alignment]
+|xref:text.adoc#text-align[Text alignment]
 |Yes
 |`:text-align: left`
 
@@ -157,7 +157,7 @@ Chinese and Japanese are written without spaces (and may not use spaces when mix
 This setting allows a line break to be placed between any two CJK characters to accommodate wrapping.
 These languages also use different punctuation for pause, full stop, and dash, which are taken into account when breaking lines.
 9. _(Experimental)_ The `text-align` document attribute is intended as a simple way to toggle text justification.
-The value of this attribute overrides the `base-align` key set by the theme.
+The value of this attribute overrides the `base-text-align` key set by the theme.
 For more fine-grained control, you should customize using the theme.
 10. The title page is only enabled by default for the book doctype.
 To force the title page to be used for other doctypes, set the `title-page` attribute in the document header.
diff --git a/docs/modules/theme/pages/base.adoc b/docs/modules/theme/pages/base.adoc
index 76c9d7d9..c3c0006d 100644
--- a/docs/modules/theme/pages/base.adoc
+++ b/docs/modules/theme/pages/base.adoc
@@ -14,12 +14,12 @@ TIP: While it's common to define additional keys in this category (e.g., `base-b
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
 (default: `left`)
 |[source]
 base:
-  align: justify
+  text-align: justify
 
 |border-color
 |xref:color.adoc[Color] +
diff --git a/docs/modules/theme/pages/block-image.adoc b/docs/modules/theme/pages/block-image.adoc
index 86e09491..0c50e879 100644
--- a/docs/modules/theme/pages/block-image.adoc
+++ b/docs/modules/theme/pages/block-image.adoc
@@ -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:text.adoc#align[Text alignment] {vbar} inherit +
+|xref:block.adoc#align[Alignment] {vbar} inherit +
 (default: `$caption-align`)
 |[source]
 image:
@@ -169,7 +169,7 @@ image:
     max-width: fit-content
 
 |caption-text-align
-|xref:text.adoc#align[Text alignment] {vbar} inherit +
+|xref:text.adoc#text-align[Text alignment] {vbar} inherit +
 (default: `$image-caption-align`)
 |[source]
 image:
diff --git a/docs/modules/theme/pages/blocks.adoc b/docs/modules/theme/pages/blocks.adoc
new file mode 100644
index 00000000..4e5c9a4f
--- /dev/null
+++ b/docs/modules/theme/pages/blocks.adoc
@@ -0,0 +1,17 @@
+= Block Styles
+
+[#align]
+== 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.
+It's roughly akin to the function of the `align-self` property of a flexbox element in CSS (when the flex direction is row).
+
+The element can be aligned using the following keywords:
+
+* `left`
+* `center`
+* `right`
+
+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.
diff --git a/docs/modules/theme/pages/callout.adoc b/docs/modules/theme/pages/callout.adoc
index 1fe73a53..c59841d8 100644
--- a/docs/modules/theme/pages/callout.adoc
+++ b/docs/modules/theme/pages/callout.adoc
@@ -71,7 +71,7 @@ callout-list:
   margin-top-after-code: 0
 
 |text-align
-|xref:text.adoc#align[Text alignment] +
+|xref:text.adoc#text-align[Text alignment] +
 (default: `$list-text-align`)
 |[source]
 callout-list:
diff --git a/docs/modules/theme/pages/caption.adoc b/docs/modules/theme/pages/caption.adoc
index 26840008..c8077d1a 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:text.adoc#align[Text alignment] +
+|xref:blocks.adoc#align[Alignment] +
 (default: `left`)
 |[source]
 caption:
@@ -61,6 +61,13 @@ caption:
 caption:
   font-style: italic
 
+|text-align
+|xref:text.adoc#text-align[Text Alignment] +
+(default: `$<category>-caption-align` or `$caption-align`)
+|[source]
+caption:
+  text-align: right
+
 |text-decoration
 |xref:text.adoc#decoration[Text decoration] +
 (default: `none`)
diff --git a/docs/modules/theme/pages/cjk.adoc b/docs/modules/theme/pages/cjk.adoc
index 2f18bf25..60c87334 100644
--- a/docs/modules/theme/pages/cjk.adoc
+++ b/docs/modules/theme/pages/cjk.adoc
@@ -40,7 +40,7 @@ font:
   fallbacks:
   - Noto Serif
 base:
-  align: left
+  text-align: left
   font-family: Noto Sans CN
 codespan:
   font-family: Noto Sans Mono CN
@@ -69,7 +69,7 @@ You may also want to darken the font color since the Noto Sans SC font has a thi
 ----
 ...
 base:
-  align: left
+  text-align: left
   font-color: #000000
   font-family: Noto Sans CN
 heading:
diff --git a/docs/modules/theme/pages/heading.adoc b/docs/modules/theme/pages/heading.adoc
index 6bad6866..1957f1cb 100644
--- a/docs/modules/theme/pages/heading.adoc
+++ b/docs/modules/theme/pages/heading.adoc
@@ -11,12 +11,12 @@ The keys in the `heading` category control the style of most headings, including
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
-(default: `$base-align`)
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$base-text-align`)
 |[source]
 heading:
-  align: center
+  text-align: center
 
 |font-color
 |xref:color.adoc[Color] +
@@ -123,12 +123,12 @@ the properties of chapter titles.
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
-(default: `$heading-align`)
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$heading-text-align`)
 |[source]
 heading:
-  h2-align: center
+  h2-text-align: center
 
 |font-color
 |xref:color.adoc[Color] +
diff --git a/docs/modules/theme/pages/list.adoc b/docs/modules/theme/pages/list.adoc
index 63b1ea60..bc412a63 100644
--- a/docs/modules/theme/pages/list.adoc
+++ b/docs/modules/theme/pages/list.adoc
@@ -33,8 +33,8 @@ list:
   marker-font-color: '#3c763d'
 
 |text-align
-|xref:text.adoc#align[Text alignment] +
-(default: `$base-align`)
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$base-text-align`)
 |[source]
 list:
   text-align: left
diff --git a/docs/modules/theme/pages/sidebar.adoc b/docs/modules/theme/pages/sidebar.adoc
index 0b15d91d..914bce76 100644
--- a/docs/modules/theme/pages/sidebar.adoc
+++ b/docs/modules/theme/pages/sidebar.adoc
@@ -105,13 +105,13 @@ The keys in the `sidebar-title` category control the arrangement and style of si
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
 (default: `center`)
 |[source]
 sidebar:
   title:
-    align: left
+    text-align: left
 
 |font-color
 |xref:color.adoc[Color] +
diff --git a/docs/modules/theme/pages/table.adoc b/docs/modules/theme/pages/table.adoc
index 9c911c31..3dba33b1 100644
--- a/docs/modules/theme/pages/table.adoc
+++ b/docs/modules/theme/pages/table.adoc
@@ -41,14 +41,14 @@ table:
   border-width: 0.5
 
 |caption-align
-|xref:text.adoc#align[Text alignment] {vbar} inherit +
+|xref:block.adoc#align[Alignment] {vbar} inherit +
 (default: `$caption-align`)
 |[source]
 table:
   caption-align: inherit
 
 |caption-text-align
-|xref:text.adoc#align[Text alignment] {vbar} inherit +
+|xref:text.adoc#text-align[Text alignment] {vbar} inherit +
 (default: `$table-caption-align`)
 |[source]
 table:
diff --git a/docs/modules/theme/pages/text.adoc b/docs/modules/theme/pages/text.adoc
index 8e408baf..f85b7220 100644
--- a/docs/modules/theme/pages/text.adoc
+++ b/docs/modules/theme/pages/text.adoc
@@ -1,15 +1,20 @@
-= Text Alignment and Styles
+= Text Styles
 
-[#align]
-== Alignment
+[#text-align]
+== Text alignment
 
-The `align` key is used to align text within the parent container.
-Text can be aligned as follows:
+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:
 
 * `left`
 * `center`
 * `right`
-* `justify` (stretched to each edge)
+* `justify` (flush to each edge of the text box, if possible)
+
+The `text-align` key is distinct from the similarly-named `align` key.
+The latter key aligns a block element horizontally within its container.
 
 [#decoration]
 == Decoration
diff --git a/docs/modules/theme/pages/title-page.adoc b/docs/modules/theme/pages/title-page.adoc
index 3f1c9372..29d580ae 100644
--- a/docs/modules/theme/pages/title-page.adoc
+++ b/docs/modules/theme/pages/title-page.adoc
@@ -19,12 +19,12 @@ In that case, setting the `:notitle:` attribute only removes the document title
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
 (default: `center`)
 |[source]
 title-page:
-  align: right
+  text-align: right
 
 |<<background-color,background-color>>
 |xref:color.adoc[Color] +
@@ -116,7 +116,7 @@ The keys in the `title-page-logo` category control the arrangement of a logo on
 
 |align
 |xref:image.adoc#align[Image alignment] +
-(default: _inherit_)
+(default: `$title-page-text-align`)
 |[source]
 title-page:
   logo:
diff --git a/docs/modules/theme/pages/toc.adoc b/docs/modules/theme/pages/toc.adoc
index 03c66984..ec8c93f2 100644
--- a/docs/modules/theme/pages/toc.adoc
+++ b/docs/modules/theme/pages/toc.adoc
@@ -166,13 +166,13 @@ The keys in the `toc-title` category control the arrangement and style of the ti
 |===
 |Key |Value Type |Example
 
-|align
-|xref:text.adoc#align[Text alignment] +
-(default: `$heading-h2-align`)
+|text-align
+|xref:text.adoc#text-align[Text alignment] +
+(default: `$heading-h2-text-align`)
 |[source]
 toc:
   title:
-    align: right
+    text-align: right
 
 |font-color
 |xref:color.adoc[Color] +
diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb
index 49b11954..9b8f9c98 100644
--- a/lib/asciidoctor/pdf/converter.rb
+++ b/lib/asciidoctor/pdf/converter.rb
@@ -205,7 +205,7 @@ module Asciidoctor
         unless title_page_on
           body_start_page_number = page_number
           theme_font :heading, level: 1 do
-            layout_general_heading doc, doc.doctitle, align: (@theme.heading_h1_align&.to_sym || :center), level: 1, role: :doctitle
+            layout_general_heading doc, doc.doctitle, align: (@theme.heading_h1_text_align&.to_sym || :center), level: 1, role: :doctitle
           end if doc.header? && !doc.notitle
         end
 
@@ -402,7 +402,7 @@ module Asciidoctor
         @font_scale = 1
         @font_color = theme.base_font_color
         @text_decoration_width = theme.base_text_decoration_width
-        @base_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_align
+        @base_text_align = (align = doc.attr 'text-align') && (TextAlignmentNames.include? align) ? align : theme.base_text_align
         @base_line_height = theme.base_line_height
         @cjk_line_breaks = doc.attr? 'scripts', 'cjk'
         if (hyphen_lang = doc.attr 'hyphens') &&
@@ -662,7 +662,7 @@ module Asciidoctor
           title = %(#{title}\n<em class="subtitle">#{subtitle}</em>)
         end
         hlevel = sect.level + 1
-        align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+        align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         chapterlike = !(part = sectname == 'part') && (sectname == 'chapter' || (sect.document.doctype == 'book' && sect.level == 1))
         hidden = sect.option? 'notitle'
         hopts = { align: align, level: hlevel, part: part, chapterlike: chapterlike, outdent: !(part || chapterlike) }
@@ -752,7 +752,7 @@ module Asciidoctor
         add_dest_for_block node if node.id
         hlevel = node.level.next
         unless (align = resolve_alignment_from_role node.roles)
-          align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym
+          align = (@theme[%(heading_h#{hlevel}_text_align)] || @theme.heading_text_align || @base_text_align).to_sym
         end
         # QUESTION: should we decouple styles from section titles?
         theme_font :heading, level: hlevel do
@@ -765,10 +765,10 @@ module Asciidoctor
         outdent_section do
           pad_box @theme.abstract_padding do
             theme_font :abstract_title do
-              layout_prose node.title, align: (@theme.abstract_title_align || @base_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              layout_prose node.title, align: (@theme.abstract_title_text_align || @base_text_align).to_sym, margin_top: @theme.heading_margin_top, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
             end if node.title?
             theme_font :abstract do
-              prose_opts = { align: (@theme.abstract_align || @base_align).to_sym, hyphenate: true }
+              prose_opts = { align: (@theme.abstract_text_align || @base_text_align).to_sym, hyphenate: true }
               if (text_indent = @theme.prose_text_indent) > 0
                 prose_opts[:indent_paragraphs] = text_indent
               end
@@ -858,7 +858,7 @@ module Asciidoctor
 
       def convert_admonition node
         type = node.attr 'name'
-        label_align = @theme.admonition_label_align&.to_sym || :center
+        label_align = @theme.admonition_label_text_align&.to_sym || :center
         # TODO: allow vertical_align to be a number
         if (label_valign = @theme.admonition_label_vertical_align&.to_sym || :middle) == :middle
           label_valign = :center
@@ -1124,7 +1124,7 @@ module Asciidoctor
           pad_box @theme.sidebar_padding, node do
             theme_font :sidebar_title do
               # QUESTION: should we allow margins of sidebar title to be customized?
-              layout_prose node.title, align: (@theme.sidebar_title_align || @theme.heading_align || @base_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
+              layout_prose node.title, align: (@theme.sidebar_title_text_align || @theme.heading_text_align || @base_text_align).to_sym, margin_bottom: @theme.heading_margin_bottom, line_height: (@theme.heading_line_height || @theme.base_line_height)
             end if node.title?
             theme_font :sidebar do
               traverse node
@@ -1555,7 +1555,7 @@ module Asciidoctor
 
         alignment = (alignment = node.attr 'align') ?
           ((BlockAlignmentNames.include? alignment) ? alignment.to_sym : :left) :
-          (resolve_alignment_from_role node.roles) || (@theme.image_align&.to_sym || :left)
+          (resolve_alignment_from_role node.roles) || @theme.image_align&.to_sym || :left
         # TODO: support cover (aka canvas) image layout using "canvas" (or "cover") role
         width = resolve_explicit_width node.attributes, bounds_width: (available_w = bounds.width), support_vw: true, use_fallback: true, constrain_to_bounds: true
         # TODO: add `to_pt page_width` method to ViewportWidth type
@@ -2750,7 +2750,7 @@ module Asciidoctor
         font @theme.base_font_family, size: @root_font_size, style: @theme.base_font_style
 
         # QUESTION: allow alignment per element on title page?
-        title_align = (@theme.title_page_align || @base_align).to_sym
+        title_align = (@theme.title_page_text_align || @base_text_align).to_sym
 
         if @theme.title_page_logo_display != 'none' && (logo_image_path = (doc.attr 'title-logo-image') || (logo_image_from_theme = @theme.title_page_logo_image))
           if (logo_image_path.include? ':') && logo_image_path =~ ImageAttributeValueRx
@@ -2981,7 +2981,7 @@ module Asciidoctor
           typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
             color: @font_color,
             inline_format: inline_format_opts,
-            align: @base_align.to_sym,
+            align: @base_text_align.to_sym,
           }.merge(opts)
           margin_bottom bot_margin
         end
@@ -3012,7 +3012,7 @@ module Asciidoctor
         typeset_text string, (calc_line_metrics (opts.delete :line_height) || @base_line_height), {
           color: @font_color,
           inline_format: [inline_format_opts],
-          align: @base_align.to_sym,
+          align: @base_text_align.to_sym,
         }.merge(opts)
         margin_bottom bot_margin
       end
@@ -3057,9 +3057,9 @@ module Asciidoctor
         container_width = bounds.width
         indent_by = [0, 0]
         if (align = @theme[%(#{category_caption}_align)] || @theme.caption_align)
-          align = align == 'inherit' ? (block_align || @base_align.to_sym) : align.to_sym
+          align = align == 'inherit' ? (block_align || @base_text_align.to_sym) : align.to_sym
         else
-          align = @base_align.to_sym
+          align = @base_text_align.to_sym
         end
         if (text_align = @theme[%(#{category_caption}_text_align)] || @theme.caption_text_align)
           text_align = text_align == 'inherit' ? align : text_align.to_sym
@@ -3152,7 +3152,7 @@ module Asciidoctor
         move_cursor_to start_cursor
         unless (toc_title = doc.attr 'toc-title').nil_or_empty?
           theme_font_cascade [[:heading, level: 2], :toc_title] do
-            toc_title_align = (@theme.toc_title_align || @theme.heading_h2_align || @theme.heading_align || @base_align).to_sym
+            toc_title_align = (@theme.toc_title_text_align || @theme.heading_h2_text_align || @theme.heading_text_align || @base_text_align).to_sym
             layout_general_heading doc, toc_title, align: toc_title_align, level: 2, outdent: true, role: :toctitle
           end
         end
@@ -4259,7 +4259,7 @@ module Asciidoctor
           (align_role.slice 5, align_role.length).to_sym
         elsif use_theme
           roles.reverse.each do |role|
-            if (align = @theme[%(role_#{role}_align)])
+            if (align = @theme[%(role_#{role}_text_align)])
               return align.to_sym
             end
           end
diff --git a/lib/asciidoctor/pdf/theme_loader.rb b/lib/asciidoctor/pdf/theme_loader.rb
index 442280ab..c67817dc 100644
--- a/lib/asciidoctor/pdf/theme_loader.rb
+++ b/lib/asciidoctor/pdf/theme_loader.rb
@@ -15,6 +15,9 @@ module Asciidoctor
       BaseThemePath = ::File.join ThemesDir, 'base-theme.yml'
       BundledThemeNames = (::Dir.children ThemesDir).map {|it| it.slice 0, it.length - 10 }
       DeprecatedCategoryKeys = { 'blockquote' => 'quote', 'key' => 'kbd', 'literal' => 'codespan', 'outline_list' => 'list' }
+      AmbiguousAlignKeys = %w(base heading heading_h1 heading_h2 heading_h3 heading_h4 heading_h5 heading_h6 title_page abstract abstract_title admonition_label sidebar_title toc_title).each_with_object({}) do |prefix, accum|
+        accum[%(#{prefix}_align)] = %(#{prefix}_text_align)
+      end
 
       VariableRx = /\$([a-z0-9_-]+)/
       LoneVariableRx = /^\$([a-z0-9_-]+)$/
@@ -22,6 +25,7 @@ module Asciidoctor
       MultiplyDivideOpRx = %r((-?\d+(?:\.\d+)?) +([*/^]) +(-?\d+(?:\.\d+)?))
       AddSubtractOpRx = /(-?\d+(?:\.\d+)?) +([+\-]) +(-?\d+(?:\.\d+)?)/
       PrecisionFuncRx = /^(round|floor|ceil)\(/
+      RoleAlignKeyRx = /(?:_text)?_align$/
 
       module ColorValue; end
 
@@ -77,7 +81,7 @@ module Asciidoctor
         else
           theme_data = load_file theme_path, nil, theme_dir
           unless (::File.dirname theme_path) == ThemesDir
-            theme_data.base_align ||= 'left'
+            theme_data.base_text_align ||= 'left'
             theme_data.base_line_height ||= 1
             theme_data.base_font_color ||= '000000'
             theme_data.code_font_family ||= (theme_data.codespan_font_family || 'Courier')
@@ -166,6 +170,9 @@ module Asciidoctor
           val.each do |subkey, subval|
             process_entry %(#{key}_#{key == 'role' || !(subkey.include? '-') ? subkey : (subkey.tr '-', '_')}), subval, data
           end
+        elsif (rekey = AmbiguousAlignKeys[key]) ||
+            ((key.start_with? 'role_') && (key.end_with? '_align') && (rekey = key.sub RoleAlignKeyRx, '_text_align'))
+          data[rekey] = evaluate val, data
         # QUESTION: do we really need to evaluate_math in this case?
         elsif key.end_with? '_color'
           if key == 'table_border_color'
@@ -208,7 +215,8 @@ module Asciidoctor
       def resolve_var vars, ref, var
         var = var.tr '-', '_' if var.include? '-'
         if (vars.respond_to? var) ||
-            DeprecatedCategoryKeys.any? {|old, new| (var.start_with? old + '_') && (vars.respond_to? (replace = new + (var.slice old.length, var.length))) && (var = replace) }
+            DeprecatedCategoryKeys.any? {|old, new| (var.start_with? old + '_') && (vars.respond_to? (replace = new + (var.slice old.length, var.length))) && (var = replace) } ||
+            ((replace = AmbiguousAlignKeys[var]) && (vars.respond_to? replace) && (var = replace))
           vars[var]
         else
           logger.warn %(unknown variable reference in PDF theme: #{ref})
diff --git a/spec/abstract_spec.rb b/spec/abstract_spec.rb
index 75761974..d1c581d7 100644
--- a/spec/abstract_spec.rb
+++ b/spec/abstract_spec.rb
@@ -15,7 +15,7 @@ describe 'Asciidoctor::PDF::Converter - Abstract' do
   end
 
   it 'should outdent abstract title and body' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { section_indent: 36, abstract_title_align: :left }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { section_indent: 36, abstract_title_text_align: :left }, analyze: true
     = Document Title
     :doctype: book
 
@@ -230,7 +230,7 @@ describe 'Asciidoctor::PDF::Converter - Abstract' do
   end
 
   it 'should allow theme to set text alignment of abstract' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { abstract_align: 'center' }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { abstract_text_align: 'center' }, analyze: true
     = Document Title
 
     [abstract]
@@ -245,7 +245,7 @@ describe 'Asciidoctor::PDF::Converter - Abstract' do
   end
 
   it 'should allow theme to set text alignment of abstract title' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { abstract_title_align: 'center' }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { abstract_title_text_align: 'center' }, analyze: true
     = Document Title
     :doctype: book
 
@@ -264,7 +264,7 @@ describe 'Asciidoctor::PDF::Converter - Abstract' do
   end
 
   it 'should use base align to align abstract title if theme does not specify alignment' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { base_align: 'center', abstract_title_align: nil }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { base_text_align: 'center', abstract_title_text_align: nil }, analyze: true
     = Document Title
     :doctype: book
 
diff --git a/spec/admonition_spec.rb b/spec/admonition_spec.rb
index b8b1a532..131df699 100644
--- a/spec/admonition_spec.rb
+++ b/spec/admonition_spec.rb
@@ -338,7 +338,7 @@ describe 'Asciidoctor::PDF::Converter - Admonition' do
     it 'should allow the theme to specify a minimum width for the text-based label' do
       pdf_theme = {
         admonition_label_min_width: '75',
-        admonition_label_align: 'right',
+        admonition_label_text_align: 'right',
       }
 
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
@@ -436,7 +436,7 @@ describe 'Asciidoctor::PDF::Converter - Admonition' do
     it 'should allow the theme to specify a minimum width for the font-based icon label' do
       pdf_theme = {
         admonition_label_min_width: '75',
-        admonition_label_align: 'right',
+        admonition_label_text_align: 'right',
       }
 
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
diff --git a/spec/document_title_spec.rb b/spec/document_title_spec.rb
index 7cad8c64..f77a7134 100644
--- a/spec/document_title_spec.rb
+++ b/spec/document_title_spec.rb
@@ -65,8 +65,8 @@ describe 'Asciidoctor::PDF::Converter - Document Title' do
       (expect doctitle_text[:y]).to be > body_text[:y]
     end
 
-    it 'should align document title according to value of heading_h1_align theme key' do
-      pdf = to_pdf <<~'EOS', pdf_theme: { heading_h1_align: 'left' }, analyze: true
+    it 'should align document title according to value of heading_h1_text_align theme key' do
+      pdf = to_pdf <<~'EOS', pdf_theme: { heading_h1_text_align: 'left' }, analyze: true
       = Document Title
 
       body
diff --git a/spec/floating_title_spec.rb b/spec/floating_title_spec.rb
index b3635d0a..173087c1 100644
--- a/spec/floating_title_spec.rb
+++ b/spec/floating_title_spec.rb
@@ -5,7 +5,7 @@ require_relative 'spec_helper'
 describe 'Asciidoctor::PDF::Converter - Floating Title' do
   it 'should apply alignment defined for headings in theme' do
     pdf_theme = {
-      heading_align: 'center',
+      heading_text_align: 'center',
     }
     pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
     [discrete]
@@ -21,8 +21,8 @@ describe 'Asciidoctor::PDF::Converter - Floating Title' do
 
   it 'should apply alignment defined for heading level in theme' do
     pdf_theme = {
-      heading_align: 'left',
-      heading_h2_align: 'center',
+      heading_text_align: 'left',
+      heading_h2_text_align: 'center',
     }
     pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
     [discrete]
@@ -38,9 +38,9 @@ describe 'Asciidoctor::PDF::Converter - Floating Title' do
 
   it 'should use base align to align floating title if theme does not specify alignemnt' do
     pdf_theme = {
-      base_align: 'center',
-      heading_h2_align: nil,
-      heading_align: nil,
+      base_text_align: 'center',
+      heading_h2_text_align: nil,
+      heading_text_align: nil,
     }
     pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true
     [discrete]
diff --git a/spec/paragraph_spec.rb b/spec/paragraph_spec.rb
index 37c7c0fe..b10ce9ef 100644
--- a/spec/paragraph_spec.rb
+++ b/spec/paragraph_spec.rb
@@ -131,8 +131,8 @@ describe 'Asciidoctor::PDF::Converter - Paragraph' do
     (expect disclaimer_text[:font_name]).to eql 'NotoSerif-Italic'
   end
 
-  it 'should use base align if caption align is set to inherit' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { base_align: 'right', caption_align: 'inherit' }, analyze: true
+  it 'should use base text align if caption align is set to inherit' do
+    pdf = to_pdf <<~'EOS', pdf_theme: { base_text_align: 'right', caption_align: 'inherit' }, analyze: true
     .Title
     Text
     EOS
@@ -198,7 +198,7 @@ describe 'Asciidoctor::PDF::Converter - Paragraph' do
     pdf_theme = {
       role_custom_font_size: 14,
       role_custom_font_color: 'FF0000',
-      role_custom_align: :center,
+      role_custom_text_align: :center,
       role_custom_font_style: 'bold',
       role_custom_text_transform: 'lowercase',
     }
diff --git a/spec/section_spec.rb b/spec/section_spec.rb
index 9b62c965..1527f958 100644
--- a/spec/section_spec.rb
+++ b/spec/section_spec.rb
@@ -145,7 +145,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do
   end
 
   it 'should allow theme to align all section titles' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { heading_align: 'center' }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { heading_text_align: 'center' }, analyze: true
     == Drill
 
     content
@@ -171,7 +171,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do
   end
 
   it 'should allow theme to align section title for specific level' do
-    pdf = to_pdf <<~'EOS', pdf_theme: { heading_h1_align: 'center' }, analyze: true
+    pdf = to_pdf <<~'EOS', pdf_theme: { heading_h1_text_align: 'center' }, analyze: true
     = Document Title
     :notitle:
     :doctype: book
diff --git a/spec/sidebar_spec.rb b/spec/sidebar_spec.rb
index c1e6b14c..72d767b6 100644
--- a/spec/sidebar_spec.rb
+++ b/spec/sidebar_spec.rb
@@ -111,11 +111,11 @@ describe 'Asciidoctor::PDF::Converter - Sidebar' do
     (expect title_text[:x]).to be > 100
     (expect title_text[:y]).to be < sidebar_border_top
 
-    pdf = to_pdf input, pdf_theme: { sidebar_title_align: nil, heading_align: 'center' }, analyze: true
+    pdf = to_pdf input, pdf_theme: { sidebar_title_text_align: nil, heading_text_align: 'center' }, analyze: true
     title_text = pdf.find_unique_text 'Sidebar Title'
     (expect title_text[:x]).to be > 100
 
-    pdf = to_pdf input, pdf_theme: { sidebar_title_align: nil, heading_align: nil }, analyze: true
+    pdf = to_pdf input, pdf_theme: { sidebar_title_text_align: nil, heading_text_align: nil }, analyze: true
     title_text = pdf.find_unique_text 'Sidebar Title'
     (expect title_text[:x]).to be < 100
   end
diff --git a/spec/theme_loader_spec.rb b/spec/theme_loader_spec.rb
index 68aca2cc..d19600f1 100644
--- a/spec/theme_loader_spec.rb
+++ b/spec/theme_loader_spec.rb
@@ -155,6 +155,37 @@ describe Asciidoctor::PDF::ThemeLoader do
       (expect theme.footer_recto_right_content).to eql '2 * 2'
     end
 
+    it 'should remap align keys to text-align keys' do
+      (expect do
+        theme_data = YAML.safe_load <<~'EOS'
+        base:
+          align: center
+        heading:
+          align: left
+          h2:
+            align: right
+        sidebar:
+          title:
+            align: $heading-align
+        caption:
+          align: $base-align
+          text-align: $heading-align
+        EOS
+        theme = subject.new.load theme_data
+        (expect theme).to be_an OpenStruct
+        (expect theme.base_align).to be_nil
+        (expect theme.base_text_align).to eql 'center'
+        (expect theme.heading_align).to be_nil
+        (expect theme.heading_text_align).to eql 'left'
+        (expect theme.heading_h2_align).to be_nil
+        (expect theme.heading_h2_text_align).to eql 'right'
+        (expect theme.sidebar_title_align).to be_nil
+        (expect theme.sidebar_title_text_align).to eql 'left'
+        (expect theme.caption_align).to eql 'center'
+        (expect theme.caption_text_align).to eql 'left'
+      end).to not_log_message
+    end
+
     it 'should remap outline-list category to list category and warn' do
       (expect do
         theme_data = YAML.safe_load <<~'EOS'
@@ -431,10 +462,10 @@ describe Asciidoctor::PDF::ThemeLoader do
           - #{File.basename custom_theme_path}
           - ./#{File.basename red_theme_path}
           base:
-            align: justify
+            text-align: justify
           EOS
             theme = subject.load_file theme_path, nil, (File.dirname theme_path)
-            (expect theme.base_align).to eql 'justify'
+            (expect theme.base_text_align).to eql 'justify'
             (expect theme.base_font_family).to eql 'Times-Roman'
             (expect theme.base_font_color).to eql 'FF0000'
           end
@@ -447,10 +478,10 @@ describe Asciidoctor::PDF::ThemeLoader do
       extends:
       - #{fixture_file 'custom-theme.yml'}
       base:
-        align: justify
+        text-align: justify
       EOS
         theme = subject.load_file theme_path
-        (expect theme.base_align).to eql 'justify'
+        (expect theme.base_text_align).to eql 'justify'
         (expect theme.base_font_family).to eql 'Times-Roman'
       end
     end
@@ -767,11 +798,11 @@ describe Asciidoctor::PDF::ThemeLoader do
           - ./#{File.basename custom_theme_path}
           - ./#{File.basename red_theme_path}
           base:
-            align: justify
+            text-align: justify
           EOS
             theme = subject.load_theme theme_path, fixtures_dir
             (expect theme.__dir__).to eql fixtures_dir
-            (expect theme.base_align).to eql 'justify'
+            (expect theme.base_text_align).to eql 'justify'
             (expect theme.base_font_family).to eql 'Times-Roman'
             (expect theme.base_font_color).to eql 'FF0000'
           end
@@ -793,11 +824,11 @@ describe Asciidoctor::PDF::ThemeLoader do
           - #{File.basename custom_theme_path}
           - #{File.basename red_theme_path}
           base:
-            align: justify
+            text-align: justify
           EOS
             theme = subject.load_theme theme_path
             (expect theme.__dir__).to eql File.dirname theme_path
-            (expect theme.base_align).to eql 'justify'
+            (expect theme.base_text_align).to eql 'justify'
             (expect theme.base_font_family).to eql 'Times-Roman'
             (expect theme.base_font_color).to eql 'FF0000'
           end
@@ -808,7 +839,7 @@ describe Asciidoctor::PDF::ThemeLoader do
     it 'should ensure required keys are set in non-built-in theme' do
       theme = subject.load_theme 'bare-theme.yml', fixtures_dir
       (expect theme.__dir__).to eql fixtures_dir
-      (expect theme.base_align).to eql 'left'
+      (expect theme.base_text_align).to eql 'left'
       (expect theme.base_line_height).to be 1
       (expect theme.base_font_color).to eql '000000'
       (expect theme.code_font_family).to eql 'Courier'
@@ -851,7 +882,7 @@ describe Asciidoctor::PDF::ThemeLoader do
         font-color: 222222
       EOS
         theme = subject.load_theme (File.basename theme_path), (File.dirname theme_path)
-        (expect theme.base_align).to eql 'justify'
+        (expect theme.base_text_align).to eql 'justify'
         (expect theme.code_font_family).to eql 'M+ 1mn'
         (expect theme.conum_font_family).to eql 'M+ 1mn'
       end
diff --git a/spec/title_page_spec.rb b/spec/title_page_spec.rb
index 3bb680c4..08abad85 100644
--- a/spec/title_page_spec.rb
+++ b/spec/title_page_spec.rb
@@ -277,7 +277,7 @@ describe 'Asciidoctor::PDF::Converter - Title Page' do
     it 'should inherit align value from title page if align not specified on logo in theme' do
       pdf_theme = {
         title_page_logo_align: nil,
-        title_page_align: 'center',
+        title_page_text_align: 'center',
       }
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: :image
       = Document Title
@@ -293,7 +293,7 @@ describe 'Asciidoctor::PDF::Converter - Title Page' do
     it 'should inherit align attribute if value on macro is invalid' do
       pdf_theme = {
         title_page_logo_align: nil,
-        title_page_align: 'left',
+        title_page_text_align: 'left',
       }
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: :image
       = Document Title
@@ -956,7 +956,7 @@ describe 'Asciidoctor::PDF::Converter - Title Page' do
       body
       EOS
 
-      theme_overrides = { title_page_align: 'left' }
+      theme_overrides = { title_page_text_align: 'left' }
 
       pdf = to_pdf input, doctype: :book, pdf_theme: theme_overrides, analyze: true
 
diff --git a/spec/toc_spec.rb b/spec/toc_spec.rb
index cff2a7c9..7272ed85 100644
--- a/spec/toc_spec.rb
+++ b/spec/toc_spec.rb
@@ -1259,25 +1259,25 @@ describe 'Asciidoctor::PDF::Converter - TOC' do
   it 'should use fallback value to align toc title if alignment not specified in theme' do
     [
       {
-        toc_title_align: 'center',
-        heading_h2_align: 'left',
-        heading_align: 'left',
+        toc_title_text_align: 'center',
+        heading_h2_text_align: 'left',
+        heading_text_align: 'left',
       },
       {
-        toc_title_align: nil,
-        heading_h2_align: 'center',
-        heading_align: 'left',
+        toc_title_text_align: nil,
+        heading_h2_text_align: 'center',
+        heading_text_align: 'left',
       },
       {
-        toc_title_align: nil,
-        heading_h2_align: nil,
-        heading_align: 'center',
+        toc_title_text_align: nil,
+        heading_h2_text_align: nil,
+        heading_text_align: 'center',
       },
       {
-        toc_title_align: nil,
-        heading_h2_align: nil,
-        heading_align: nil,
-        base_align: 'center',
+        toc_title_text_align: nil,
+        heading_h2_text_align: nil,
+        heading_text_align: nil,
+        base_text_align: 'center',
       },
     ].each do |pdf_theme|
       pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, analyze: true