add tip about how to keep section title with multiple ensuing blocks

1 files changed, 20 insertions, 3 deletions

diff --git a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
index 1253fd35..a4a8ed00 100644
--- a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
+++ b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
@@ -62,7 +62,7 @@ The `breakable` option can be applied to a section to ensure the section title i
 [,asciidoc]
 ----
 [%breakable]
-=== Title of a section
+=== Title of Section
 
 First block of content in the section.
 ----
@@ -72,7 +72,7 @@ This option can also be added to a discrete heading to ensure the heading is kep
 [,asciidoc]
 ----
 [discrete%breakable]
-=== Discrete heading
+=== Discrete Heading
 
 Next block of content.
 ----
@@ -82,7 +82,24 @@ In other words, the option prevents a page break immediately following the title
 Instead, the page break will come _before_ the title.
 This option does not make the converter attempt to keep an entire section on the same page.
 
-If you want to enable this feature for all sections and discrete headings, you can set the `heading-min-height-after` theme key to `auto` instead.
+However, you can get the section title to stick with more than one block by wrapping the blocks that follow it in an unbreakable block.
+
+[,asciidoc]
+----
+[%breakable]
+=== Title of Section
+
+[%unbreakable]
+--
+First block of content in the section.
+
+Second block of content in the section.
+--
+----
+
+In this case, the section will follow the unbreakable block if it gets advanced to the next page.
+
+If you want to prevent all sections and discrete headings from being orphaned globally, you can set the `heading-min-height-after` theme key to `auto` instead.
 
 [,yaml]
 ----