sync-commits erge branch 'v4-dev' into custom-checkboxes-radios-correct-color

25 files changed, 297 insertions, 115 deletions

diff --git a/docs/4.0/components/alerts.md b/docs/4.0/components/alerts.md
index b8bb0c216..aa6dfbecc 100644
--- a/docs/4.0/components/alerts.md
+++ b/docs/4.0/components/alerts.md
@@ -50,7 +50,7 @@ Alerts can also contain additional HTML elements like headings, paragraphs and d
 Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how:
 
 - Be sure you've loaded the alert plugin, or the compiled Bootstrap JavaScript.
-- If you're building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util). The compiled version includes this.
+- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util). The compiled version includes this.
 - Add a dismiss button and the `.alert-dismissible` class, which adds extra padding to the right of the alert and positions the `.close` button.
 - On the dismiss button, add the `data-dismiss="alert"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices.
 - To animate alerts when dismissing them, be sure to add the `.fade` and `.show` classes.
@@ -92,6 +92,7 @@ Note that closing an alert will remove it from the DOM.
 | --- | --- |
 | `$().alert()` | Makes an alert listen for click events on descendant elements which have the `data-dismiss="alert"` attribute. (Not necessary when using the data-api's auto-initialization.) |
 | `$().alert('close')` | Closes an alert by removing it from the DOM. If the `.fade` and `.show` classes are present on the element, the alert will fade out before it is removed. |
+| `$().alert('dispose')` | Destroys an element's alert. |
 
 {% highlight js %}$(".alert").alert('close'){% endhighlight %}
 
diff --git a/docs/4.0/components/badge.md b/docs/4.0/components/badge.md
index c42d948d6..287005e7d 100644
--- a/docs/4.0/components/badge.md
+++ b/docs/4.0/components/badge.md
@@ -70,7 +70,7 @@ Use the `.badge-pill` modifier class to make badges more rounded (with a larger
 
 ## Links
 
-Using the `.badge` classes with the `<a>` element quickly provide _actionable_ badges with hover and focus states.
+Using the contextual `.badge-*` classes on an `<a>` element quickly provide _actionable_ badges with hover and focus states.
 
 {% example html %}
 {% for color in site.data.theme-colors %}
diff --git a/docs/4.0/components/buttons.md b/docs/4.0/components/buttons.md
index fac603e7e..41ca9cef0 100644
--- a/docs/4.0/components/buttons.md
+++ b/docs/4.0/components/buttons.md
@@ -154,4 +154,5 @@ Note that pre-checked buttons require you to manually add the `.active` class to
 
 | Method | Description |
 | --- | --- |
-| `$().button('toggle')` |Toggles push state. Gives the button the appearance that it has been activated.  |
+| `$().button('toggle')` | Toggles push state. Gives the button the appearance that it has been activated. |
+| `$().button('dispose')` | Destroys an element's button. |
diff --git a/docs/4.0/components/card.md b/docs/4.0/components/card.md
index 5da0ef039..76f4757ec 100644
--- a/docs/4.0/components/card.md
+++ b/docs/4.0/components/card.md
@@ -90,6 +90,19 @@ Create lists of content in a card with a flush list group.
 </div>
 {% endexample %}
 
+{% example html %}
+<div class="card" style="width: 20rem;">
+  <div class="card-header">
+    Featured
+  </div>
+  <ul class="list-group list-group-flush">
+    <li class="list-group-item">Cras justo odio</li>
+    <li class="list-group-item">Dapibus ac facilisis in</li>
+    <li class="list-group-item">Vestibulum at eros</li>
+  </ul>
+</div>
+{% endexample %}
+
 ### Kitchen sink
 
 Mix and match multiple content types to create the card you need, or throw everything in there. Shown below are image styles, blocks, text styles, and a list group—all wrapped in a fixed-width card.
diff --git a/docs/4.0/components/carousel.md b/docs/4.0/components/carousel.md
index 4919e1ac2..af2648267 100644
--- a/docs/4.0/components/carousel.md
+++ b/docs/4.0/components/carousel.md
@@ -14,7 +14,7 @@ In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibilit
 
 Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards.
 
-Lastly, if you're building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+Lastly, if you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
 
 ## Example
 
@@ -263,6 +263,10 @@ Cycles to the previous item. **Returns to the caller before the previous item ha
 
 Cycles to the next item. **Returns to the caller before the next item has been shown** (i.e. before the `slid.bs.carousel` event occurs).
 
+### `.carousel('dispose')`
+
+Destroys an element's carousel.
+
 ### Events
 
 Bootstrap's carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties:
diff --git a/docs/4.0/components/collapse.md b/docs/4.0/components/collapse.md
index a34ffeb7b..cd0a7d4e5 100644
--- a/docs/4.0/components/collapse.md
+++ b/docs/4.0/components/collapse.md
@@ -226,6 +226,10 @@ Shows a collapsible element. **Returns to the caller before the collapsible elem
 
 Hides a collapsible element. **Returns to the caller before the collapsible element has actually been hidden** (i.e. before the `hidden.bs.collapse` event occurs).
 
+### `.collapse('dispose')`
+
+Destroys an element's collapse.
+
 ### Events
 
 Bootstrap's collapse class exposes a few events for hooking into collapse functionality.
diff --git a/docs/4.0/components/dropdowns.md b/docs/4.0/components/dropdowns.md
index d38b410c7..f91ff5312 100644
--- a/docs/4.0/components/dropdowns.md
+++ b/docs/4.0/components/dropdowns.md
@@ -12,7 +12,7 @@ Dropdowns are toggleable, contextual overlays for displaying lists of links and
 
 Dropdowns are built on a third party library, [Popper.js](https://popper.js.org/), which provides dynamic positioning and viewport detection. Be sure to include [popper.min.js]({{ site.cdn.popper }}) before Bootstrap's JavaScript or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js.
 
-If you're building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
 
 ## Accessibility
 
@@ -607,6 +607,7 @@ Options can be passed via data attributes or JavaScript. For data attributes, ap
 | --- | --- |
 | `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. |
 | `$().dropdown('update')` | Updates the position of an element's dropdown. |
+| `$().dropdown('dispose')` | Destroys an element's dropdown. |
 
 ### Events
 
diff --git a/docs/4.0/components/forms.md b/docs/4.0/components/forms.md
index ed4d95b70..abf6c1e67 100644
--- a/docs/4.0/components/forms.md
+++ b/docs/4.0/components/forms.md
@@ -264,11 +264,11 @@ The `.form-group` class is the easiest way to add some structure to forms. Its o
 {% example html %}
 <form>
   <div class="form-group">
-    <label class="form-control-label" for="formGroupExampleInput">Example label</label>
+    <label class="col-form-label" for="formGroupExampleInput">Example label</label>
     <input type="text" class="form-control" id="formGroupExampleInput" placeholder="Example input">
   </div>
   <div class="form-group">
-    <label class="form-control-label" for="formGroupExampleInput2">Another label</label>
+    <label class="col-form-label" for="formGroupExampleInput2">Another label</label>
     <input type="text" class="form-control" id="formGroupExampleInput2" placeholder="Another input">
   </div>
 </form>
@@ -314,36 +314,36 @@ More complex layouts can also be created with the grid system.
 <form>
   <div class="form-row">
     <div class="form-group col-md-6">
-      <label for="inputEmail4" class="col-form-label">Email</label>
+      <label for="inputEmail4">Email</label>
       <input type="email" class="form-control" id="inputEmail4" placeholder="Email">
     </div>
     <div class="form-group col-md-6">
-      <label for="inputPassword4" class="col-form-label">Password</label>
+      <label for="inputPassword4">Password</label>
       <input type="password" class="form-control" id="inputPassword4" placeholder="Password">
     </div>
   </div>
   <div class="form-group">
-    <label for="inputAddress" class="col-form-label">Address</label>
+    <label for="inputAddress">Address</label>
     <input type="text" class="form-control" id="inputAddress" placeholder="1234 Main St">
   </div>
   <div class="form-group">
-    <label for="inputAddress2" class="col-form-label">Address 2</label>
+    <label for="inputAddress2">Address 2</label>
     <input type="text" class="form-control" id="inputAddress2" placeholder="Apartment, studio, or floor">
   </div>
   <div class="form-row">
     <div class="form-group col-md-6">
-      <label for="inputCity" class="col-form-label">City</label>
+      <label for="inputCity">City</label>
       <input type="text" class="form-control" id="inputCity">
     </div>
     <div class="form-group col-md-4">
-      <label for="inputState" class="col-form-label">State</label>
+      <label for="inputState">State</label>
       <select id="inputState" class="form-control">
         <option selected>Choose...</option>
         <option>...</option>
       </select>
     </div>
     <div class="form-group col-md-2">
-      <label for="inputZip" class="col-form-label">Zip</label>
+      <label for="inputZip">Zip</label>
       <input type="text" class="form-control" id="inputZip">
     </div>
   </div>
@@ -365,62 +365,87 @@ Create horizontal forms with the grid by adding the `.row` class to form groups
 Be sure to add `.col-form-label` to your `<label>`s as well so they're vertically centered with their associated form controls. For `<legend>` elements, you can use `.col-form-legend` to make them appear similar to regular `<label>` elements.
 
 {% example html %}
-<div class="container">
-  <form>
-    <div class="form-group row">
-      <label for="inputEmail3" class="col-sm-2 col-form-label">Email</label>
-      <div class="col-sm-10">
-        <input type="email" class="form-control" id="inputEmail3" placeholder="Email">
-      </div>
+<form>
+  <div class="form-group row">
+    <label for="inputEmail3" class="col-sm-2 col-form-label">Email</label>
+    <div class="col-sm-10">
+      <input type="email" class="form-control" id="inputEmail3" placeholder="Email">
     </div>
-    <div class="form-group row">
-      <label for="inputPassword3" class="col-sm-2 col-form-label">Password</label>
-      <div class="col-sm-10">
-        <input type="password" class="form-control" id="inputPassword3" placeholder="Password">
-      </div>
+  </div>
+  <div class="form-group row">
+    <label for="inputPassword3" class="col-sm-2 col-form-label">Password</label>
+    <div class="col-sm-10">
+      <input type="password" class="form-control" id="inputPassword3" placeholder="Password">
     </div>
-    <fieldset class="form-group">
-      <div class="row">
-        <legend class="col-form-legend col-sm-2">Radios</legend>
-        <div class="col-sm-10">
-          <div class="form-check">
-            <label class="form-check-label">
-              <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios1" value="option1" checked>
-              Option one is this and that&mdash;be sure to include why it's great
-            </label>
-          </div>
-          <div class="form-check">
-            <label class="form-check-label">
-              <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios2" value="option2">
-              Option two can be something else and selecting it will deselect option one
-            </label>
-          </div>
-          <div class="form-check disabled">
-            <label class="form-check-label">
-              <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios3" value="option3" disabled>
-              Option three is disabled
-            </label>
-          </div>
-        </div>
-      </div>
-    </fieldset>
-    <div class="form-group row">
-      <div class="col-sm-2">Checkbox</div>
+  </div>
+  <fieldset class="form-group">
+    <div class="row">
+      <legend class="col-form-legend col-sm-2">Radios</legend>
       <div class="col-sm-10">
         <div class="form-check">
           <label class="form-check-label">
-            <input class="form-check-input" type="checkbox"> Check me out
+            <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios1" value="option1" checked>
+            Option one is this and that&mdash;be sure to include why it's great
+          </label>
+        </div>
+        <div class="form-check">
+          <label class="form-check-label">
+            <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios2" value="option2">
+            Option two can be something else and selecting it will deselect option one
+          </label>
+        </div>
+        <div class="form-check disabled">
+          <label class="form-check-label">
+            <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios3" value="option3" disabled>
+            Option three is disabled
           </label>
         </div>
       </div>
     </div>
-    <div class="form-group row">
-      <div class="col-sm-10">
-        <button type="submit" class="btn btn-primary">Sign in</button>
+  </fieldset>
+  <div class="form-group row">
+    <div class="col-sm-2">Checkbox</div>
+    <div class="col-sm-10">
+      <div class="form-check">
+        <label class="form-check-label">
+          <input class="form-check-input" type="checkbox"> Check me out
+        </label>
       </div>
     </div>
-  </form>
-</div>
+  </div>
+  <div class="form-group row">
+    <div class="col-sm-10">
+      <button type="submit" class="btn btn-primary">Sign in</button>
+    </div>
+  </div>
+</form>
+{% endexample %}
+
+##### Horizontal form label sizing
+
+Be sure to use `.col-form-label-sm` or `.col-form-label-lg` to your `<label>`s to correctly follow the size of `.form-control-lg` and `.form-control-sm`.
+
+{% example html %}
+<form>
+  <div class="form-group row">
+    <label for="colFormLabelSm" class="col-sm-2 col-form-label col-form-label-sm">Email</label>
+    <div class="col-sm-10">
+      <input type="email" class="form-control form-control-sm" id="colFormLabelSm" placeholder="col-form-label-sm">
+    </div>
+  </div>
+  <div class="form-group row">
+    <label for="colFormLabel" class="col-sm-2 col-form-label">Email</label>
+    <div class="col-sm-10">
+      <input type="email" class="form-control" id="colFormLabel" placeholder="col-form-label">
+    </div>
+  </div>
+  <div class="form-group row">
+    <label for="colFormLabelLg" class="col-sm-2 col-form-label col-form-label-lg">Email</label>
+    <div class="col-sm-10">
+      <input type="email" class="form-control form-control-lg" id="colFormLabelLg" placeholder="col-form-label-lg">
+    </div>
+  </div>
+</form>
 {% endexample %}
 
 #### Column sizing
diff --git a/docs/4.0/components/modal.md b/docs/4.0/components/modal.md
index 491bd3fb8..c4191b83d 100644
--- a/docs/4.0/components/modal.md
+++ b/docs/4.0/components/modal.md
@@ -359,11 +359,11 @@ Below is a live demo followed by example HTML and JavaScript. For more informati
       <div class="modal-body">
         <form>
           <div class="form-group">
-            <label for="recipient-name" class="form-control-label">Recipient:</label>
+            <label for="recipient-name" class="col-form-label">Recipient:</label>
             <input type="text" class="form-control" id="recipient-name">
           </div>
           <div class="form-group">
-            <label for="message-text" class="form-control-label">Message:</label>
+            <label for="message-text" class="col-form-label">Message:</label>
             <textarea class="form-control" id="message-text"></textarea>
           </div>
         </form>
@@ -575,6 +575,10 @@ Manually readjust the modal's position if the height of a modal changes while it
 
 {% highlight js %}$('#myModal').modal('handleUpdate'){% endhighlight %}
 
+### `.modal('dispose')`
+
+Destroys an element's modal.
+
 ### Events
 
 Bootstrap's modal class exposes a few events for hooking into modal functionality. All modal events are fired at the modal itself (i.e. at the `<div class="modal">`).
diff --git a/docs/4.0/components/navbar.md b/docs/4.0/components/navbar.md
index f303aa2bc..a40b68897 100644
--- a/docs/4.0/components/navbar.md
+++ b/docs/4.0/components/navbar.md
@@ -12,8 +12,9 @@ Here's what you need to know before getting started with the navbar:
 
 - Navbars require a wrapping `.navbar` with `.navbar-expand{-sm|-md|-lg|-xl}` for responsive collapsing and [color scheme](#color-schemes) classes.
 - Navbars and their contents are fluid by default. Use [optional containers](#containers) to limit their horizontal width.
-- Navbars and their contents are built with flexbox, providing easy alignment options via utility classes.
+- Use our [spacing]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/) and [flex]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/flex/) utility classes for controlling spacing and alignment within navbars.
 - Navbars are responsive by default, but you can easily modify them to change that. Responsive behavior depends on our Collapse JavaScript plugin.
+- Navbars are hidden by default when printing. Force them to be printed by adding `.d-print` to the `.navbar`. See the [display]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/display/) utility class. 
 - Ensure accessibility by using a `<nav>` element or, if using a more generic element such as a `<div>`, add a `role="navigation"` to every navbar to explicitly identify it as a landmark region for users of assistive technologies.
 
 Read on for an example and list of supported sub-components.
@@ -46,6 +47,17 @@ Here's an example of all the sub-components included in a responsive light-theme
       <li class="nav-item">
         <a class="nav-link" href="#">Link</a>
       </li>
+      <li class="nav-item dropdown">
+        <a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+          Dropdown
+        </a>
+        <div class="dropdown-menu" aria-labelledby="navbarDropdown">
+          <a class="dropdown-item" href="#">Action</a>
+          <a class="dropdown-item" href="#">Another action</a>
+          <div class="dropdown-divider"></div>
+          <a class="dropdown-item" href="#">Something else here</a>
+        </div>
+      </li>
       <li class="nav-item">
         <a class="nav-link disabled" href="#">Disabled</a>
       </li>
@@ -58,6 +70,8 @@ Here's an example of all the sub-components included in a responsive light-theme
 </nav>
 {% endexample %}
 
+This example uses [color]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/colors/) (`bg-light`) and [spacing]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/) (`my-2`, `my-lg-0`, `mr-sm-0`, `my-sm-0`) utility classes.
+
 ### Brand
 
 The `.navbar-brand` can be applied to most elements, but an anchor works best as some elements might require utility classes or custom styles.
@@ -395,11 +409,13 @@ When the container is within your navbar, its horizontal padding is removed at b
 
 ## Placement
 
-Use our position utilities to place navbars in non-static positions. Choose from fixed to the top, fixed to the bottom, or stickied to the top. **Note that `position: sticky`, used for `.sticky-top`, [isn't fully supported in every browser](https://caniuse.com/#feat=css-sticky).**
+Use our [position utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/position/) to place navbars in non-static positions. Choose from fixed to the top, fixed to the bottom, or stickied to the top (scrolls with the page until it reaches the top, then stays there). Fixed navbars use `position: fixed`, meaning they're pulled from the normal flow of the DOM and may require custom CSS (e.g., `padding-top` on the `<body>`) to prevent overlap with other elements.
+
+Also note that **`.sticky-top` uses `position: sticky`, which [isn't fully supported in every browser](https://caniuse.com/#feat=css-sticky)**.
 
 {% example html %}
 <nav class="navbar navbar-light bg-light">
-  <a class="navbar-brand" href="#">Full width</a>
+  <a class="navbar-brand" href="#">Default</a>
 </nav>
 {% endexample %}
 
diff --git a/docs/4.0/components/navs.md b/docs/4.0/components/navs.md
index b34f79c2f..20e822353 100644
--- a/docs/4.0/components/navs.md
+++ b/docs/4.0/components/navs.md
@@ -297,7 +297,7 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
 
 Use the tab JavaScript plugin—include it individually or through the compiled `bootstrap.js` file—to extend our navigational tabs and pills to create tabbable panes of local content, even via dropdown menus.
 
-If you're building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
 
 Dynamic tabbed interfaces, as described in the [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr> Authoring Practices](https://www.w3.org/TR/wai-aria-practices/#tabpanel), require `role="tablist"`, `role="tab"`, `role="tabpanel"`, and additional `aria-` attributes in order to convey their structure, functionality and current state to users of assistive technologies (such as screen readers).
 
@@ -583,6 +583,10 @@ Selects the given tab and shows its associated pane. Any other tab that was prev
 $('#someTab').tab('show')
 {% endhighlight %}
 
+### .tab('dispose')
+
+Destroys an element's tab.
+
 ### Events
 
 When showing a new tab, the events fire in the following order:
diff --git a/docs/4.0/components/popovers.md b/docs/4.0/components/popovers.md
index b8356b0d2..31ff5c61f 100644
--- a/docs/4.0/components/popovers.md
+++ b/docs/4.0/components/popovers.md
@@ -13,16 +13,16 @@ Things to know when using the popover plugin:
 
 - Popovers rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning. You must include [popper.min.js]({{ site.cdn.popper }}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js in order for popovers to work!
 - Popovers require the [tooltip plugin]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/tooltips/) as a dependency.
-- If building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
 - Popovers are opt-in for performance reasons, so **you must initialize them yourself**.
 - Zero-length `title` and `content` values will never show a popover.
 - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
 - Triggering popovers on hidden elements will not work.
 - Popovers for `.disabled` or `disabled` elements must be triggered on a wrapper element.
-- When triggered from hyperlinks that span multiple lines, popovers will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
+- When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors' overall width. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
 - Popovers must be hidden before their corresponding elements have been removed from the DOM.
 
-Got all that? Great, let's see how they work with some examples.
+Keep reading to see how popovers work with some examples.
 
 ## Example: Enable popovers everywhere
 
@@ -132,7 +132,7 @@ sagittis lacus vel augue laoreet rutrum faucibus.">
 
 ### Dismiss on next click
 
-Use the `focus` trigger to dismiss popovers on the next click that the user makes.
+Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element.
 
 {% callout danger %}
 #### Specific markup required for dismiss-on-next-click
diff --git a/docs/4.0/components/scrollspy.md b/docs/4.0/components/scrollspy.md
index b7f9e994f..ef528b0f0 100644
--- a/docs/4.0/components/scrollspy.md
+++ b/docs/4.0/components/scrollspy.md
@@ -10,8 +10,8 @@ toc: true
 
 Scrollspy has a few requirements to function properly:
 
-- If building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
-- It must to be used on a Bootstrap [nav component]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/navs/) or [list group]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/list-group/).
+- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+- It must be used on a Bootstrap [nav component]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/navs/) or [list group]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/list-group/).
 - Scrollspy requires `position: relative;` on the element you're spying on, usually the `<body>`.
 - When spying on elements other than the `<body>`, be sure to have a `height` set and `overflow-y: scroll;` applied.
 - Anchors (`<a>`) are required and must point to an element with that `id`.
@@ -280,6 +280,9 @@ $('[data-spy="scroll"]').each(function () {
 })
 {% endhighlight %}
 
+### `.scrollspy('dispose')`
+
+Destroys an element's scrollspy.
 
 ### Options
 
diff --git a/docs/4.0/components/tooltips.md b/docs/4.0/components/tooltips.md
index d3598048d..766b726ed 100644
--- a/docs/4.0/components/tooltips.md
+++ b/docs/4.0/components/tooltips.md
@@ -11,7 +11,7 @@ toc: true
 Things to know when using the tooltip plugin:
 
 - Tooltips rely on the 3rd party library [Popper.js](https://popper.js.org/) for positioning. You must include [popper.min.js]({{ site.cdn.popper }}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js in order for tooltips to work!
-- If building our JS from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
 - Tooltips are opt-in for performance reasons, so **you must initialize them yourself**.
 - Tooltips with zero-length titles are never displayed.
 - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc).
diff --git a/docs/4.0/content/tables.md b/docs/4.0/content/tables.md
index 59bdb6373..d4506c2c9 100644
--- a/docs/4.0/content/tables.md
+++ b/docs/4.0/content/tables.md
@@ -579,11 +579,48 @@ Regular table background variants are not available with the dark table, however
 {% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %}
 {{ callout-include | markdownify }}
 
-## Responsive tables
 
-Create responsive tables by adding `.table-responsive{-sm|-md|-lg|-xl}` to any `.table` to make them scroll horizontally at each `max-width` breakpoint 575px, 767px, 991px, and 1199px, respectively.
+## Captions
 
-For responsive tables that always scroll horizontally when the table is wider than its container, add the `.table-responsive` class on `.table`.
+A `<caption>` functions like a heading for a table. It helps users with screen readers to find a table and understand what it’s about and decide if they want to read it.
+
+{% example html %}
+<table class="table">
+  <caption>List of users</caption>
+  <thead>
+    <tr>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">1</th>
+      <td>Mark</td>
+      <td>Otto</td>
+      <td>@mdo</td>
+    </tr>
+    <tr>
+      <th scope="row">2</th>
+      <td>Jacob</td>
+      <td>Thornton</td>
+      <td>@fat</td>
+    </tr>
+    <tr>
+      <th scope="row">3</th>
+      <td>Larry</td>
+      <td>the Bird</td>
+      <td>@twitter</td>
+    </tr>
+  </tbody>
+</table>
+{% endexample %}
+
+## Responsive tables
+
+Responsive tables allow tables to be scrolled horizontally with ease. Make any table responsive across all viewports by adding `.table-responsive` class on `.table`. Or, pick a maximum breakpoint with which to have a responsive table up to by adding `.table-responsive{-sm|-md|-lg|-xl}`.
 
 {% callout warning %}
 #### Vertical clipping/truncation
@@ -591,6 +628,8 @@ For responsive tables that always scroll horizontally when the table is wider th
 Responsive tables make use of `overflow-y: hidden`, which clips off any content that goes beyond the bottom or top edges of the table. In particular, this can clip off dropdown menus and other third-party widgets.
 {% endcallout %}
 
+### Always responsive
+
 <div class="bd-example">
   <table class="table table-responsive">
     <thead>
@@ -697,41 +736,57 @@ Responsive tables make use of `overflow-y: hidden`, which clips off any content
 </table>
 {% endhighlight %}
 
+### Breakpoint specific
 
-## Captions
+Use `.table-responsive{-sm|-md|-lg|-xl}` as needed to create responsive tables up to a particular breakpoint. From that breakpoint and up, the table will behave normally and not scroll horizontally.
 
-A `<caption>` functions like a heading for a table. It helps users with screen readers to find a table and understand what it’s about and decide if they want to read it.
-
-{% example html %}
-<table class="table">
-  <caption>List of users</caption>
+<div class="bd-example">
+{% for bp in site.data.breakpoints %}{% unless bp.breakpoint == "xs" %}
+<table class="table table-responsive{{ bp.abbr }}">
   <thead>
     <tr>
       <th scope="col">#</th>
-      <th scope="col">First Name</th>
-      <th scope="col">Last Name</th>
-      <th scope="col">Username</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <th scope="row">1</th>
-      <td>Mark</td>
-      <td>Otto</td>
-      <td>@mdo</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
     <tr>
       <th scope="row">2</th>
-      <td>Jacob</td>
-      <td>Thornton</td>
-      <td>@fat</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
     <tr>
       <th scope="row">3</th>
-      <td>Larry</td>
-      <td>the Bird</td>
-      <td>@twitter</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
   </tbody>
 </table>
-{% endexample %}
+{% endunless %}{% endfor %}
+</div>
+
+{% highlight html %}
+{% for bp in site.data.breakpoints %}{% unless bp.breakpoint == "xs" %}
+<table class="table table-responsive{{ bp.abbr }}">
+  ...
+</table>
+{% endunless %}{% endfor %}
+{% endhighlight %}
diff --git a/docs/4.0/examples/navbar-bottom/index.html b/docs/4.0/examples/navbar-bottom/index.html
index 3046f9b9b..675428c54 100644
--- a/docs/4.0/examples/navbar-bottom/index.html
+++ b/docs/4.0/examples/navbar-bottom/index.html
@@ -21,7 +21,7 @@
         <a class="btn btn-lg btn-primary" href="../../components/navbar/" role="button">View navbar docs &raquo;</a>
       </div>
     </div>
-    <nav class="navbar fixed-bottom navbar-expand navbar-dark bg-dark">
+    <nav class="navbar fixed-bottom navbar-expand-sm navbar-dark bg-dark">
       <a class="navbar-brand" href="#">Bottom navbar</a>
       <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
         <span class="navbar-toggler-icon"></span>
diff --git a/docs/4.0/getting-started/accessibility.md b/docs/4.0/getting-started/accessibility.md
index 09d51064e..0f9e87ae1 100644
--- a/docs/4.0/getting-started/accessibility.md
+++ b/docs/4.0/getting-started/accessibility.md
@@ -49,5 +49,5 @@ For visually hidden interactive controls, such as traditional "skip" links, `.sr
 - [The A11Y Project](http://a11yproject.com/)
 - [MDN accessibility documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
 - [Tenon.io Accessibility Checker](https://tenon.io/)
-- [Colour Contrast Analyser (CCA)](https://www.paciellogroup.com/resources/contrastanalyser/)
+- [Colour Contrast Analyser (CCA)](https://developer.paciellogroup.com/resources/contrastanalyser/)
 - ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer)
diff --git a/docs/4.0/getting-started/build-tools.md b/docs/4.0/getting-started/build-tools.md
index 4eb37e312..3a569af24 100644
--- a/docs/4.0/getting-started/build-tools.md
+++ b/docs/4.0/getting-started/build-tools.md
@@ -46,7 +46,7 @@ Running our documentation locally requires the use of Jekyll, a decently flexibl
 
 1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and other Ruby dependencies with `bundle install`.
 2. From the root `/bootstrap` directory, run `npm run docs-serve` in the command line.
-3. Open <http://localhost:9001> in your browser, and voilà.
+3. Open `http://localhost:9001` in your browser, and voilà.
 
 Learn more about using Jekyll by reading its [documentation](https://jekyllrb.com/docs/home/).
 
diff --git a/docs/4.0/getting-started/download.md b/docs/4.0/getting-started/download.md
index 9f1199317..c93d6dc34 100644
--- a/docs/4.0/getting-started/download.md
+++ b/docs/4.0/getting-started/download.md
@@ -68,13 +68,13 @@ Bootstrap's `package.json` contains some additional metadata under the following
 Install Bootstrap in your Ruby apps using [Bundler](https://bundler.io/) (**recommended**) and [RubyGems](https://rubygems.org/) by adding the following line to your [`Gemfile`](https://bundler.io/gemfile.html):
 
 {% highlight ruby %}
-gem 'bootstrap', '~> 4.0.0.beta'
+gem 'bootstrap', '~> {{ site.current_ruby_version }}'
 {% endhighlight %}
 
 Alternatively, if you're not using Bundler, you can install the gem by running this command:
 
 {% highlight sh %}
-gem install bootstrap -v 4.0.0.beta
+gem install bootstrap -v {{ site.current_ruby_version }}
 {% endhighlight %}
 
 [See the gem's README](https://github.com/twbs/bootstrap-rubygem/blob/master/README.md) for further details.
diff --git a/docs/4.0/getting-started/javascript.md b/docs/4.0/getting-started/javascript.md
index 648132255..a0094d154 100644
--- a/docs/4.0/getting-started/javascript.md
+++ b/docs/4.0/getting-started/javascript.md
@@ -120,6 +120,6 @@ Bootstrap's plugins don't fall back particularly gracefully when JavaScript is d
 
 ## Util
 
-All Bootstrap's JavaScript files depend on `util.js` and it has to be included alongside the other JS files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
+All Bootstrap's JavaScript files depend on `util.js` and it has to be included alongside the other JavaScript files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
 
 `util.js` includes utility functions and a basic helper for `transitionEnd` events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.
diff --git a/docs/4.0/getting-started/theming.md b/docs/4.0/getting-started/theming.md
index 15c5caa0b..12f309aaf 100644
--- a/docs/4.0/getting-started/theming.md
+++ b/docs/4.0/getting-started/theming.md
@@ -11,7 +11,7 @@ redirect_from: "/docs/4.0/getting-started/options/"
 
 In Bootstrap 3, theming was largely driven by variable overrides in LESS, custom CSS, and a separate theme stylesheet that we included in our `dist` files. With some effort, one could completely redesign the look of Bootstrap 3 without touching the core files. Bootstrap 4 provides a familiar, but slightly different approach.
 
-Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet anymore; instead, you can enable the built-in theme to add gradients, shadows, and more.
+Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet; instead, you can enable the built-in theme to add gradients, shadows, and more.
 
 ## Sass
 
@@ -19,7 +19,7 @@ Utilize our source Sass files to take advantage of variables, maps, mixins, and
 
 ### File structure
 
-Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you've downloaded our source files or are using package manager, you'll have a file structure that looks like this:
+Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you've downloaded our source files or are using a package manager, you'll have a file structure that looks like this:
 
 {% highlight plaintext %}
 your-project/
@@ -148,6 +148,36 @@ In practice, you'd call the function and pass in two parameters: the name of the
 
 Additional functions could be added in the future or your own custom Sass to create level functions for additional Sass maps, or even a generic one if you wanted to be more verbose.
 
+### Color contrast
+
+One additional function we include in Bootstrap is the color contrast function, `color-yiq`. It utilizes the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
+
+For example, to generate color swatches from our `$theme-colors` map:
+
+{% highlight scss %}
+@each $color, $value in $theme-colors {
+  .swatch-#{$color} {
+    color: color-yiq($value);
+  }
+}
+{% endhighlight %}
+
+It can also be used for one-off contrast needs:
+
+{% highlight scss %}
+.custom-element {
+  color: color-yiq(#000); // returns `color: #fff`
+}
+{% endhighlight %}
+
+You can also specify a base color with our color map functions:
+
+{% highlight scss %}
+.custom-element {
+  color: color-yiq(theme-color("dark")); // returns `color: #fff`
+}
+{% endhighlight %}
+
 ## Sass options
 
 Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
@@ -172,7 +202,7 @@ Many of Bootstrap's various components and utilities are built through a series
 
 ### All colors
 
-All colors available in Bootstrap 4, available as Sass variables and a Sass map in our `scss/_variables.scss` file. This will be expanded upon in subsequent minor releases to add additional shades, much like the [grayscale palette](#grays) we already include.
+All colors available in Bootstrap 4, are available as Sass variables and a Sass map in our `scss/_variables.scss` file. This will be expanded upon in subsequent minor releases to add additional shades, much like the [grayscale palette](#grays) we already include.
 
 <div class="row">
   {% for color in site.data.colors %}
diff --git a/docs/4.0/layout/overview.md b/docs/4.0/layout/overview.md
index c86a432d3..4952da5b7 100644
--- a/docs/4.0/layout/overview.md
+++ b/docs/4.0/layout/overview.md
@@ -163,8 +163,8 @@ We don't encourage customization of these values; should you change one, you lik
 
 ```scss
 $zindex-dropdown:          1000 !default;
+$zindex-sticky:            1020 !default;
 $zindex-fixed:             1030 !default;
-$zindex-sticky:            1030 !default;
 $zindex-modal-backdrop:    1040 !default;
 $zindex-modal:             1050 !default;
 $zindex-popover:           1060 !default;
@@ -172,3 +172,5 @@ $zindex-tooltip:           1070 !default;
 ```
 
 Background elements—like the backdrops that allow click-dismissing—tend to reside on a lower `z-index`s, while navigation and popovers utilize higher `z-index`s to ensure they overlay surrounding content.
+
+Additionally, the `button-group`, `input-group`, `list-group`, and `pagination` components make use of setting `z-index` to `1` or `2` in order to ensure that the borders of the _active_ element correctly appear "above" their sibling elements.
diff --git a/docs/4.0/migration.md b/docs/4.0/migration.md
index 8a0d3d3fa..c8c1fd6b4 100644
--- a/docs/4.0/migration.md
+++ b/docs/4.0/migration.md
@@ -17,7 +17,9 @@ While in beta, we aim to have no breaking changes. However, things don't always
 - Renamed `.table-inverse`, `.thead-inverse`, and `.thead-default` to `.*-dark` and `.*-light`, matching our color schemes used elsewhere.
 - Responsive tables now generate classes for each grid breakpoint. This breaks from Beta 1 in that the `.table-responsive` you've been using is more like `.table-responsive-md`. You may now use `.table-responsive` or `.table-responsive-{sm,md,lg,xl}` as needed.
 - Dropped Bower support as the package manager has been deprecated for alternatives (e.g., Yarn or npm). [See bower/bower#2298](https://github.com/bower/bower/issues/2298) for details.
-- Bootstrap now requires jQuery 3.0.0 or higher.
+- Bootstrap still requires jQuery 1.9.1 or higher, but you're advised to use version 3.x since v3.x's supported browsers are the ones Bootstrap supports plus v3.x has some security fixes.
+- Removed the unused `.form-control-label` class. If you did make use of this class, it was duplicate of the `.col-form-label` class that vertically centered a `<label>` with it's associated input in horizontal form layouts.
+- Changed the `color-yiq` from a mixin that included the `color` property to a function that returns a value, allowing you to use it for any CSS property. For example, instead of `color-yiq(#000)`, you'd write `color: color-yiq(#000);`.
 
 ### Highlights
 
@@ -109,7 +111,7 @@ New to Bootstrap 4 is the [Reboot]({{ site.baseurl }}/docs/{{ site.docs_version
 ### Forms
 
 - Moved element resets to the `_reboot.scss` file.
-- Renamed `.control-label` to `.form-control-label`.
+- Renamed `.control-label` to `.col-form-label`.
 - Renamed `.input-lg` and `.input-sm` to `.form-control-lg` and `.form-control-sm`, respectively.
 - Dropped `.form-group-*` classes for simplicity's sake. Use `.form-control-*` classes instead now.
 - Dropped `.help-block` and replaced it with `.form-text` for block-level help text. For inline help text and other flexible options, use utility classes like `.text-muted`.
@@ -118,7 +120,7 @@ New to Bootstrap 4 is the [Reboot]({{ site.baseurl }}/docs/{{ site.docs_version
 - Horizontal forms overhauled:
   - Dropped the `.form-horizontal` class requirement.
   - `.form-group` no longer applies styles from the `.row` via mixin, so `.row` is now required for horizontal grid layouts (e.g., `<div class="form-group row">`).
-  - Added new `.form-control-label` class to vertically center labels with `.form-control`s.
+  - Added new `.col-form-label` class to vertically center labels with `.form-control`s.
   - Added new `.form-row` for compact form layouts with the grid classes (swap your `.row` for a `.form-row` and go).
 - Added custom forms support (for checkboxes, radios, selects, and file inputs).
 - Replaced `.has-error`, `.has-warning`, and `.has-success` classes with HTML5 form validation via CSS's `:invalid` and `:valid` pseudo-classes.
@@ -128,7 +130,7 @@ New to Bootstrap 4 is the [Reboot]({{ site.baseurl }}/docs/{{ site.docs_version
 
 - Renamed `.btn-default` to `.btn-secondary`.
 - Dropped the `.btn-xs` class entirely as `.btn-sm` is proportionally much smaller than v3's.
-- The [stateful button]({{ site.baseurl }}/docs/3.3/javascript/#buttons-stateful) feature of the `button.js` jQuery plugin has been dropped. This includes the `$().button(string)` and `$().button('reset')` methods. We advise using a tiny bit of custom JavaScript instead, which will have the benefit of behaving exactly the way you want it to.
+- The [stateful button]({{ site.url }}/docs/3.3/javascript/#buttons-stateful) feature of the `button.js` jQuery plugin has been dropped. This includes the `$().button(string)` and `$().button('reset')` methods. We advise using a tiny bit of custom JavaScript instead, which will have the benefit of behaving exactly the way you want it to.
   - Note that the other features of the plugin (button checkboxes, button radios, single-toggle buttons) have been retained in v4.
 - Change buttons' `[disabled]` to `:disabled` as IE9+ supports `:disabled`. However `fieldset[disabled]` is still necessary because [native disabled fieldsets are still buggy in IE11](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#Browser_compatibility).
 
diff --git a/docs/4.0/utilities/colors.md b/docs/4.0/utilities/colors.md
index 13c0adc8a..10d6e5ae3 100644
--- a/docs/4.0/utilities/colors.md
+++ b/docs/4.0/utilities/colors.md
@@ -6,6 +6,8 @@ group: utilities
 toc: true
 ---
 
+## Color
+
 {% example html %}
 {% for color in site.data.theme-colors %}
 <p class="text-{{ color.name }}{% if color.name == "light" %} bg-dark{% endif %}">.text-{{ color.name }}</p>{% endfor %}
@@ -22,6 +24,8 @@ Contextual text classes also work well on anchors with the provided hover and fo
 <p><a href="#" class="text-white bg-dark">White link</a></p>
 {% endexample %}
 
+## Background color
+
 Similar to the contextual text color classes, easily set the background of an element to any contextual class. Anchor components will darken on hover, just like the text classes. Background utilities **do not set `color`**, so in some cases you'll want to use `.text-*` utilities.
 
 {% example html %}
@@ -30,6 +34,15 @@ Similar to the contextual text color classes, easily set the background of an el
 <div class="p-3 mb-2 bg-white text-dark">.bg-white</div>
 {% endexample %}
 
+## Background gradient
+
+When `$enable-gradients` is set to true, you'll be able to use `.bg-gradient-` utility classes. **By default, `$enable-gradients` is disabled and the example below is intentionally broken.** This is done for easier customization from the moment you start using Bootstrap. [Learn about our Sass options]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/theming/#sass-options) to enable these classes and more.
+
+{% example html %}
+{% for color in site.data.theme-colors %}
+<div class="p-3 mb-2 bg-gradient-{{ color.name }} {% if color.name == "light" %}text-dark{% else %}text-white{% endif %}">.bg-gradient-{{ color.name }}</div>{% endfor %}
+{% endexample %}
+
 {% callout info %}
 #### Dealing with specificity
 
diff --git a/docs/4.0/utilities/flex.md b/docs/4.0/utilities/flex.md
index 1d28fab6d..470a7db72 100644
--- a/docs/4.0/utilities/flex.md
+++ b/docs/4.0/utilities/flex.md
@@ -215,20 +215,24 @@ Responsive variations also exist for `align-self`.
 
 ## Auto margins
 
-Flexbox can do some pretty awesome things when you mix flex alignments with auto margins.
+Flexbox can do some pretty awesome things when you mix flex alignments with auto margins. Shown below are three examples of controlling flex items via auto margins: default (no auto margin), pushing two items to the right (`.mr-auto`), and pushing two items to the left (`.ml-auto`).
 
-### With justify-content
-
-Easily move all flex items to one side, but keep another on the opposite end by mixing `justify-content` with `margin-right: auto` or `margin-left: auto`.
+**Unfortunately, IE10 and IE11 do not properly support auto margins on flex items whose parent has a non-default `justify-content` value.** [See this StackOverflow answer](https://stackoverflow.com/a/37535548) for more details.
 
 {% example html %}
-<div class="d-flex justify-content-end bd-highlight mb-3">
+<div class="d-flex bd-highlight mb-3">
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+  <div class="p-2 bd-highlight">Flex item</div>
+</div>
+
+<div class="d-flex bd-highlight mb-3">
   <div class="mr-auto p-2 bd-highlight">Flex item</div>
   <div class="p-2 bd-highlight">Flex item</div>
   <div class="p-2 bd-highlight">Flex item</div>
 </div>
 
-<div class="d-flex justify-content-start bd-highlight">
+<div class="d-flex bd-highlight mb-3">
   <div class="p-2 bd-highlight">Flex item</div>
   <div class="p-2 bd-highlight">Flex item</div>
   <div class="ml-auto p-2 bd-highlight">Flex item</div>
@@ -237,7 +241,7 @@ Easily move all flex items to one side, but keep another on the opposite end by
 
 ### With align-items
 
-Similarly, move one flex item to the top or bottom of a container by mixing `align-items`, `flex-direction: column`, and `margin-top: auto` or `margin-bottom: auto`.
+Vertically move one flex item to the top or bottom of a container by mixing `align-items`, `flex-direction: column`, and `margin-top: auto` or `margin-bottom: auto`.
 
 {% example html %}
 <div class="d-flex align-items-start flex-column bd-highlight mb-3" style="height: 200px;">