1 files changed, 56 insertions, 16 deletions
diff --git a/docs/components/button-dropdown.md b/docs/components/button-dropdown.md
index ecad0d862..80d8911b9 100644
--- a/docs/components/button-dropdown.md
+++ b/docs/components/button-dropdown.md
@@ -17,9 +17,9 @@ Button dropdowns require the [dropdown plugin]({{ site.baseurl }}/components/dro
 * Will be replaced with the ToC, excluding the "Contents" header
 {:toc}
 
-### Single button dropdowns
+## Single button dropdowns
 
-Turn a button into a dropdown toggle with some basic markup changes.
+Turn a button into a dropdown toggle with some basic markup changes for the menu itself and the button used to trigger it.
 
 <div class="bd-example">
   <div class="btn-group">
@@ -100,9 +100,11 @@ Turn a button into a dropdown toggle with some basic markup changes.
 </div>
 {% endhighlight %}
 
-### Split button dropdowns
+## Split button dropdowns
 
-Similarly, create split button dropdowns with nearly the same markup as single button dropdowns, but add the `.dropdown-toggle-split` class for proper spacing around the dropdown caret.
+Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` for proper spacing around the dropdown caret.
+
+We use this extra class to reduce the horizontal `padding` on either side of the caret by 25% and remove the `margin-left` that's added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button.
 
 <div class="bd-example">
   <div class="btn-group">
@@ -202,9 +204,9 @@ Similarly, create split button dropdowns with nearly the same markup as single b
 </div>
 {% endhighlight %}
 
-### Sizing
+## Sizing
 
-Button dropdowns work with buttons of all sizes.
+Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.
 
 <div class="bd-example">
   <div class="btn-toolbar" role="toolbar">
@@ -264,37 +266,58 @@ Button dropdowns work with buttons of all sizes.
 </div><!-- /example -->
 
 {% highlight html %}
-<!-- Large button group -->
+<!-- Large button groups (default and split) -->
+<div class="btn-group">
+  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+    Large button
+  </button>
+  <div class="dropdown-menu">
+    ...
+  </div>
+</div>
 <div class="btn-group">
   <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
     Large button
   </button>
+  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+    <span class="sr-only">Toggle Dropdown</span>
+  </button>
   <div class="dropdown-menu">
     ...
   </div>
 </div>
 
-<!-- Small button group -->
+<!-- Small button groups (default and split) -->
+<div class="btn-group">
+  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+    Small button
+  </button>
+  <div class="dropdown-menu">
+    ...
+  </div>
+</div>
 <div class="btn-group">
   <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
     Small button
   </button>
+  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+    <span class="sr-only">Toggle Dropdown</span>
+  </button>
   <div class="dropdown-menu">
     ...
   </div>
 </div>
 {% endhighlight %}
 
-### Dropup variation
+## Dropup variation
 
 Trigger dropdown menus above elements by adding `.dropup` to the parent.
 
 <div class="bd-example">
   <div class="btn-toolbar" role="toolbar">
     <div class="btn-group dropup">
-      <button type="button" class="btn btn-secondary">Dropup</button>
       <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
-        <span class="sr-only">Toggle Dropdown</span>
+        Dropup
       </button>
       <div class="dropdown-menu">
         <a class="dropdown-item" href="#">Action</a>
@@ -303,24 +326,28 @@ Trigger dropdown menus above elements by adding `.dropup` to the parent.
         <div class="dropdown-divider"></div>
         <a class="dropdown-item" href="#">Separated link</a>
       </div>
-    </div><!-- /btn-group -->
+    </div>
+
     <div class="btn-group dropup">
-      <button type="button" class="btn btn-primary">Right dropup</button>
-      <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+      <button type="button" class="btn btn-secondary">
+        Split dropup
+      </button>
+      <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
         <span class="sr-only">Toggle Dropdown</span>
       </button>
-      <div class="dropdown-menu dropdown-menu-right">
+      <div class="dropdown-menu">
         <a class="dropdown-item" href="#">Action</a>
         <a class="dropdown-item" href="#">Another action</a>
         <a class="dropdown-item" href="#">Something else here</a>
         <div class="dropdown-divider"></div>
         <a class="dropdown-item" href="#">Separated link</a>
       </div>
-    </div><!-- /btn-group -->
+    </div>
   </div>
 </div>
 
 {% highlight html %}
+<!-- Default dropup button -->
 <div class="btn-group dropup">
   <button type="button" class="btn btn-secondary">Dropup</button>
   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
@@ -330,4 +357,17 @@ Trigger dropdown menus above elements by adding `.dropup` to the parent.
     <!-- Dropdown menu links -->
   </div>
 </div>
+
+<!-- Split dropup button -->
+<div class="btn-group dropup">
+  <button type="button" class="btn btn-secondary">
+    Split dropup
+  </button>
+  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+    <span class="sr-only">Toggle Dropdown</span>
+  </button>
+  <div class="dropdown-menu">
+    <!-- Dropdown menu links -->
+  </div>
+</div>
 {% endhighlight %}