Increase margins and line-height on h3; overhaul button dropdown docs

3 files changed, 59 insertions, 189 deletions

diff --git a/docs/assets/css/bootstrap.css b/docs/assets/css/bootstrap.css
index 30fb6de1a..cf075b0a7 100644
--- a/docs/assets/css/bootstrap.css
+++ b/docs/assets/css/bootstrap.css
@@ -441,13 +441,17 @@ h6 small {
 }
 
 h1,
-h2 {
+h2,
+h3 {
   margin-top: 20px;
   margin-bottom: 10px;
   line-height: 40px;
 }
 
-h3,
+h3 {
+  line-height: 30px;
+}
+
 h4,
 h5,
 h6 {
diff --git a/docs/components.html b/docs/components.html
index 49db6f6bb..fdc317e8c 100644
--- a/docs/components.html
+++ b/docs/components.html
@@ -174,7 +174,6 @@
           <div class="page-header">
             <h1>Button groups</h1>
           </div>
-
           <p class="lead">Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with <a href="./javascript.html#buttons">our buttons plugin</a>.</p>
 
           <h3>Single button group</h3>
@@ -263,12 +262,12 @@
           <div class="page-header">
             <h1>Button dropdown menus</h1>
           </div>
+          <p class="lead">Use any button to trigger a dropdown menu by placing it within a <code>.btn-group</code> and providing the proper menu markup. Requires the <a href="./javascript.html#dropdowns">Bootstrap dropdown plugin</a>.</p>
 
-
-          <h2>Overview and examples</h2>
-          <p>Use any button to trigger a dropdown menu by placing it within a <code>.btn-group</code> and providing the proper menu markup.</p>
+          <h3>Single or split button</h3>
+          <p>Turn a button into dropdown toggle, or add a second button to toggle the dropdown while retaining the primary button action.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
+            <div class="btn-toolbar" style="margin-bottom: 10px;">
               <div class="btn-group">
                 <button class="btn dropdown-toggle" data-toggle="dropdown">Action <span class="caret"></span></button>
                 <ul class="dropdown-menu">
@@ -319,68 +318,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-          </div>
-<pre class="prettyprint linenums">
-&lt;div class="btn-group"&gt;
-  &lt;a class="btn dropdown-toggle" data-toggle="dropdown" href="#"&gt;
-    Action
-    &lt;span class="caret"&gt;&lt;/span&gt;
-  &lt;/a&gt;
-  &lt;ul class="dropdown-menu"&gt;
-    &lt;!-- dropdown menu links --&gt;
-  &lt;/ul&gt;
-&lt;/div&gt;
-</pre>
-
-          <h3>Works with all button sizes</h3>
-          <p>Button dropdowns work at any size:  <code>.btn-large</code>, <code>.btn-small</code>, or <code>.btn-mini</code>.</p>
-          <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
-              <div class="btn-group">
-                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown">Large button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-              <div class="btn-group">
-                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown">Small button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-              <div class="btn-group">
-                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown">Mini button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-          </div>
-
-          <h3>Requires JavaScript</h3>
-          <p>Button dropdowns require the <a href="./javascript.html#dropdowns">Bootstrap dropdown plugin</a> to function.</p>
-          <p>In some cases&mdash;like mobile&mdash;dropdown menus will extend outside the viewport. You need to resolve the alignment manually or with custom JavaScript.</p>
-
-
-          <hr class="bs-docs-separator">
-
+            </div>
 
-          <h2>Split button dropdowns</h2>
-          <p>Building on the button group styles and markup, we can easily create a split button. Split buttons feature a standard action on the left and a dropdown toggle on the right with contextual links.</p>
-          <div class="bs-docs-example">
             <div class="btn-toolbar" style="margin: 0;">
               <div class="btn-group">
                 <button class="btn">Action</button>
@@ -440,6 +379,18 @@
             </div><!-- /btn-toolbar -->
           </div>
 <pre class="prettyprint linenums">
+&lt;-- Single button --&gt;
+&lt;div class="btn-group"&gt;
+  &lt;button type="button" class="btn dropdown-toggle" data-toggle="dropdown"&gt;
+    Action
+    &lt;span class="caret"&gt;&lt;/span&gt;
+  &lt;/button&gt;
+  &lt;ul class="dropdown-menu"&gt;
+    &lt;!-- dropdown menu links --&gt;
+  &lt;/ul&gt;
+&lt;/div&gt;
+
+&lt;-- Split button --&gt;
 &lt;div class="btn-group"&gt;
   &lt;button class="btn"&gt;Action&lt;/button&gt;
   &lt;button class="btn dropdown-toggle" data-toggle="dropdown"&gt;
@@ -451,13 +402,12 @@
 &lt;/div&gt;
 </pre>
 
-          <h3>Sizes</h3>
-          <p>Utilize the extra button classes <code>.btn-mini</code>, <code>.btn-small</code>, or <code>.btn-large</code> for sizing.</p>
+          <h3>Works with all button sizes</h3>
+          <p>Button dropdowns work at any size: <code>.btn-large</code>, <code>.btn-small</code>, or <code>.btn-mini</code>.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar">
+            <div class="btn-toolbar" style="margin: 0;">
               <div class="btn-group">
-                <button class="btn btn-large">Large action</button>
-                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown">Large button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -466,11 +416,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-            <div class="btn-toolbar">
               <div class="btn-group">
-                <button class="btn btn-small">Small action</button>
-                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown">Small button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -479,11 +426,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-            <div class="btn-toolbar">
               <div class="btn-group">
-                <button class="btn btn-mini">Mini action</button>
-                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown">Mini button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -494,22 +438,11 @@
               </div><!-- /btn-group -->
             </div><!-- /btn-toolbar -->
           </div>
-<pre class="prettyprint linenums">
-&lt;div class="btn-group"&gt;
-  &lt;button class="btn btn-mini"&gt;Action&lt;/button&gt;
-  &lt;button class="btn btn-mini dropdown-toggle" data-toggle="dropdown"&gt;
-    &lt;span class="caret"&gt;&lt;/span&gt;
-  &lt;/button&gt;
-  &lt;ul class="dropdown-menu"&gt;
-    &lt;!-- dropdown menu links --&gt;
-  &lt;/ul&gt;
-&lt;/div&gt;
-</pre>
 
-          <h3>Dropup menus</h3>
-          <p>Dropdown menus can also be toggled from the bottom up by adding a single class to the immediate parent of <code>.dropdown-menu</code>. It will flip the direction of the <code>.caret</code> and reposition the menu itself to move from the bottom up instead of top down.</p>
+          <h3>Dropup buttons</h3>
+          <p>Trigger dropdown menus above elements by adding <code>.dropup</code> to the parent.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
+            <div class="btn-toolbar">
               <div class="btn-group dropup">
                 <button class="btn">Dropup</button>
                 <button class="btn dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
diff --git a/docs/templates/pages/components.mustache b/docs/templates/pages/components.mustache
index 791ecb854..2513fcc3e 100644
--- a/docs/templates/pages/components.mustache
+++ b/docs/templates/pages/components.mustache
@@ -106,7 +106,6 @@
           <div class="page-header">
             <h1>Button groups</h1>
           </div>
-
           <p class="lead">Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with <a href="./javascript.html#buttons">our buttons plugin</a>.</p>
 
           <h3>Single button group</h3>
@@ -195,12 +194,12 @@
           <div class="page-header">
             <h1>Button dropdown menus</h1>
           </div>
+          <p class="lead">Use any button to trigger a dropdown menu by placing it within a <code>.btn-group</code> and providing the proper menu markup. Requires the <a href="./javascript.html#dropdowns">Bootstrap dropdown plugin</a>.</p>
 
-
-          <h2>Overview and examples</h2>
-          <p>Use any button to trigger a dropdown menu by placing it within a <code>.btn-group</code> and providing the proper menu markup.</p>
+          <h3>Single or split button</h3>
+          <p>Turn a button into dropdown toggle, or add a second button to toggle the dropdown while retaining the primary button action.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
+            <div class="btn-toolbar" style="margin-bottom: 10px;">
               <div class="btn-group">
                 <button class="btn dropdown-toggle" data-toggle="dropdown">Action <span class="caret"></span></button>
                 <ul class="dropdown-menu">
@@ -251,68 +250,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-          </div>{{! /example }}
-<pre class="prettyprint linenums">
-&lt;div class="btn-group"&gt;
-  &lt;a class="btn dropdown-toggle" data-toggle="dropdown" href="#"&gt;
-    Action
-    &lt;span class="caret"&gt;&lt;/span&gt;
-  &lt;/a&gt;
-  &lt;ul class="dropdown-menu"&gt;
-    &lt;!-- dropdown menu links --&gt;
-  &lt;/ul&gt;
-&lt;/div&gt;
-</pre>
-
-          <h3>Works with all button sizes</h3>
-          <p>Button dropdowns work at any size:  <code>.btn-large</code>, <code>.btn-small</code>, or <code>.btn-mini</code>.</p>
-          <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
-              <div class="btn-group">
-                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown">Large button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-              <div class="btn-group">
-                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown">Small button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-              <div class="btn-group">
-                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown">Mini button <span class="caret"></span></button>
-                <ul class="dropdown-menu">
-                  <li><a href="#">Action</a></li>
-                  <li><a href="#">Another action</a></li>
-                  <li><a href="#">Something else here</a></li>
-                  <li class="divider"></li>
-                  <li><a href="#">Separated link</a></li>
-                </ul>
-              </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-          </div>{{! /example }}
-
-          <h3>Requires JavaScript</h3>
-          <p>Button dropdowns require the <a href="./javascript.html#dropdowns">Bootstrap dropdown plugin</a> to function.</p>
-          <p>In some cases&mdash;like mobile&mdash;dropdown menus will extend outside the viewport. You need to resolve the alignment manually or with custom JavaScript.</p>
-
-
-          <hr class="bs-docs-separator">
-
+            </div>
 
-          <h2>Split button dropdowns</h2>
-          <p>Building on the button group styles and markup, we can easily create a split button. Split buttons feature a standard action on the left and a dropdown toggle on the right with contextual links.</p>
-          <div class="bs-docs-example">
             <div class="btn-toolbar" style="margin: 0;">
               <div class="btn-group">
                 <button class="btn">Action</button>
@@ -370,8 +309,20 @@
                 </ul>
               </div><!-- /btn-group -->
             </div><!-- /btn-toolbar -->
-          </div>{{! /example }}
+          </div>
 <pre class="prettyprint linenums">
+&lt;-- Single button --&gt;
+&lt;div class="btn-group"&gt;
+  &lt;button type="button" class="btn dropdown-toggle" data-toggle="dropdown"&gt;
+    Action
+    &lt;span class="caret"&gt;&lt;/span&gt;
+  &lt;/button&gt;
+  &lt;ul class="dropdown-menu"&gt;
+    &lt;!-- dropdown menu links --&gt;
+  &lt;/ul&gt;
+&lt;/div&gt;
+
+&lt;-- Split button --&gt;
 &lt;div class="btn-group"&gt;
   &lt;button class="btn"&gt;Action&lt;/button&gt;
   &lt;button class="btn dropdown-toggle" data-toggle="dropdown"&gt;
@@ -383,13 +334,12 @@
 &lt;/div&gt;
 </pre>
 
-          <h3>Sizes</h3>
-          <p>Utilize the extra button classes <code>.btn-mini</code>, <code>.btn-small</code>, or <code>.btn-large</code> for sizing.</p>
+          <h3>Works with all button sizes</h3>
+          <p>Button dropdowns work at any size: <code>.btn-large</code>, <code>.btn-small</code>, or <code>.btn-mini</code>.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar">
+            <div class="btn-toolbar" style="margin: 0;">
               <div class="btn-group">
-                <button class="btn btn-large">Large action</button>
-                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-large dropdown-toggle" data-toggle="dropdown">Large button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -398,11 +348,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-            <div class="btn-toolbar">
               <div class="btn-group">
-                <button class="btn btn-small">Small action</button>
-                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-small dropdown-toggle" data-toggle="dropdown">Small button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -411,11 +358,8 @@
                   <li><a href="#">Separated link</a></li>
                 </ul>
               </div><!-- /btn-group -->
-            </div><!-- /btn-toolbar -->
-            <div class="btn-toolbar">
               <div class="btn-group">
-                <button class="btn btn-mini">Mini action</button>
-                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>
+                <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown">Mini button <span class="caret"></span></button>
                 <ul class="dropdown-menu">
                   <li><a href="#">Action</a></li>
                   <li><a href="#">Another action</a></li>
@@ -426,22 +370,11 @@
               </div><!-- /btn-group -->
             </div><!-- /btn-toolbar -->
           </div>{{! /example }}
-<pre class="prettyprint linenums">
-&lt;div class="btn-group"&gt;
-  &lt;button class="btn btn-mini"&gt;Action&lt;/button&gt;
-  &lt;button class="btn btn-mini dropdown-toggle" data-toggle="dropdown"&gt;
-    &lt;span class="caret"&gt;&lt;/span&gt;
-  &lt;/button&gt;
-  &lt;ul class="dropdown-menu"&gt;
-    &lt;!-- dropdown menu links --&gt;
-  &lt;/ul&gt;
-&lt;/div&gt;
-</pre>
 
-          <h3>Dropup menus</h3>
-          <p>Dropdown menus can also be toggled from the bottom up by adding a single class to the immediate parent of <code>.dropdown-menu</code>. It will flip the direction of the <code>.caret</code> and reposition the menu itself to move from the bottom up instead of top down.</p>
+          <h3>Dropup buttons</h3>
+          <p>Trigger dropdown menus above elements by adding <code>.dropup</code> to the parent.</p>
           <div class="bs-docs-example">
-            <div class="btn-toolbar" style="margin: 0;">
+            <div class="btn-toolbar">
               <div class="btn-group dropup">
                 <button class="btn">Dropup</button>
                 <button class="btn dropdown-toggle" data-toggle="dropdown"><span class="caret"></span></button>