resolves asciidoctor#1515 implement smart block bottom margins to pre…

…vent extra space below blocks, particularly nested blocks

CHANGELOG.adoc

@@ -12,6 +12,8 @@ Enhancements::
 * make delimited blocks breakable by default; require the `unbreakable` option on the block to retain the previous "`keep together`" behavior (#2004, #578, #509, #240)
 * add support for the %unbreakable option on a table to keep it from being split across pages (#2022, #871, #819, #331)
 * add support for the %breakable option on a table (special case) to keep the caption and ID with the start of the table (#2022, #993)
+* implement smart block bottom margins to prevent extra space below blocks, particularly nested blocks (#1515)
+* drop support for `top-margin` key on block and prose categories in theme; space between delimited blocks and lists now controlled using bottom margins only (#1515)
 * allow page numbering and running content to start after first page of a document without a title page by assigning an integer to the respective `start_at` theme key (#1644)
 * allow page numbering and running content to start after toc (wherever it is placed) by assigning the keyword `after-toc` to the respective `start_at` theme key (#1763)
 * allow theme to configure page numbering to start at cover (#1727)

data/themes/base-theme.yml

@@ -69,15 +69,15 @@ abstract_title_align: center
 abstract_title_font_style: bold
 admonition_column_rule_color: 'EEEEEE'
 admonition_column_rule_width: 0.5
-admonition_padding: [0, 12, 0, 12]
+admonition_padding: [4, 12, 4, 12]
 admonition_label_font_style: bold
 admonition_label_text_transform: uppercase
 blockquote_border_color: 'EEEEEE'
 blockquote_border_left_width: 4
-blockquote_padding: [6, 12, -6, 14]
+blockquote_padding: [6, 12, 6, 14]
 verse_border_color: 'EEEEEE'
 verse_border_left_width: 4
-verse_padding: [6, 12, -6, 14]
+verse_padding: [6, 12, 6, 14]
 code_font_family: Courier
 code_font_size: 10.8
 code_line_height: 1.2
@@ -90,15 +90,13 @@ conum_glyphs: circled
 example_background_color: 'FFFFFF'
 example_border_color: 'EEEEEE'
 example_border_width: 0.5
-# FIXME reenable margin bottom once margin collapsing is implemented
-example_padding: [12, 12, 0, 12]
+example_padding: 12
 image_align: left
 lead_font_size: 13.5
 lead_line_height: 1.4
 prose_margin_bottom: 12
 sidebar_background_color: 'EEEEEE'
-# FIXME reenable margin bottom once margin collapsing is implemented
-sidebar_padding: [12, 12, 0, 12]
+sidebar_padding: 12
 sidebar_title_align: center
 sidebar_title_font_style: bold
 table_border_color: '000000'

data/themes/default-theme.yml

@@ -156,7 +156,7 @@ abstract:
 admonition:
   column_rule_color: $base_border_color
   column_rule_width: $base_border_width
-  padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
+  padding: [$vertical_rhythm / 3.0, $horizontal_rhythm, $vertical_rhythm / 3.0, $horizontal_rhythm]
   #icon:
   #  tip:
   #    name: far-lightbulb
@@ -170,8 +170,7 @@ blockquote:
   border_color: $base_border_color
   border_width: 0
   border_left_width: 5
-  # FIXME disable negative padding bottom once margin collapsing is implemented
-  padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_left_width / 2]
+  padding: [0, $horizontal_rhythm, $block_margin_bottom * 0.25, $horizontal_rhythm + $blockquote_border_left_width / 2]
   cite:
     font_size: $base_font_size_small
     font_color: $role_subtitle_font_color
@@ -210,8 +209,7 @@ example:
   border_radius: $base_border_radius
   border_width: 0.75
   background_color: $page_background_color
-  # FIXME reenable padding bottom once margin collapsing is implemented
-  padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm]
+  padding: [$vertical_rhythm, $horizontal_rhythm, $vertical_rhythm, $horizontal_rhythm]
 image:
   align: left
 prose:
@@ -221,8 +219,7 @@ sidebar:
   border_color: E1E1E1
   border_radius: $base_border_radius
   border_width: $base_border_width
-  # FIXME reenable padding bottom once margin collapsing is implemented
-  padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
+  padding: [$vertical_rhythm, $vertical_rhythm * 1.25, $vertical_rhythm, $vertical_rhythm * 1.25]
   title:
     align: center
     font_color: $heading_font_color

docs/theming-guide.adoc

@@ -2352,20 +2352,20 @@ The position of the background image can be controlled using the `position` attr
 [#keys-prose]
 === Prose
 
-The keys in this category control the spacing around paragraphs (paragraph blocks, paragraph content of a block, and other prose content).
-Typically, all the margin is placed on the bottom.
+The keys in this category control the spacing below paragraphs, lists, and index categories.
+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 of any blocks).
 
 [cols="3,4,5l"]
 |===
 |Key |Value Type |Example
 
 3+|[#key-prefix-prose]*Key Prefix:* <<key-prefix-prose,prose>>
 
-|margin-top
-|<<measurement-units,Measurement>> +
-(default: 0)
-|prose:
-  margin-top: 0
+//|margin-top
+//|<<measurement-units,Measurement>> +
+//(default: 0)
+//|prose:
+//  margin-top: 0
 
 |margin-bottom
 |<<measurement-units,Measurement>> +
@@ -2392,7 +2392,9 @@ Useful when using indented paragraphs.
 [#keys-block]
 === Block
 
-The keys in this category control the spacing around block elements when a more specific setting is not designated.
+The keys in this category control the spacing below block elements when a more specific setting is not designated.
+See the second table in this section for a list of blocks to which these keys apply.
+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 of any blocks).
 
 [cols="3,4,5l"]
 |===
@@ -2405,11 +2407,11 @@ The keys in this category control the spacing around block elements when a more
 //|block:
 //  padding: [12, 15, 12, 15]
 
-|margin-top
-|<<measurement-units,Measurement>> +
-(default: 0)
-|block:
-  margin-top: 6
+//|margin-top
+//|<<measurement-units,Measurement>> +
+//(default: 0)
+//|block:
+//  margin-top: 6
 
 |margin-bottom
 |<<measurement-units,Measurement>> +