Merge branch 'twbs/v4-dev' into v4-dev

5 files changed, 104 insertions, 37 deletions

diff --git a/docs/layout/flexbox-grid.md b/docs/layout/flexbox-grid.md
index ea4fad28b..80db93c93 100644
--- a/docs/layout/flexbox-grid.md
+++ b/docs/layout/flexbox-grid.md
@@ -1,12 +1,13 @@
 ---
 layout: docs
 title: Flexbox grid system
+description: Documentation and examples for using Bootstrap's optional flexbox grid system.
 group: layout
 ---
 
-Fancy a more modern grid system? [Enable flexbox support in Bootstrap](/getting-started/flexbox) to take full advantage of CSS's Flexible Box module for even more control over your site's layout, alignment, and distribution of content.
+Fancy a more modern grid system? [Enable flexbox support in Bootstrap]({{ site.baseurl }}/getting-started/flexbox/) to take full advantage of CSS's Flexible Box module for even more control over your site's layout, alignment, and distribution of content.
 
-Bootstrap's flexbox grid includes support for every feature from our [default grid system](/layout/grid), and then some. Please read the [default grid system docs](/layout/grid) before proceeding through this page. Features that are covered there are only summarized here. Please note that **Internet Explorer 9 does not support flexbox**, so proceed with caution when enabling it.
+Bootstrap's flexbox grid includes support for every feature from our [default grid system]({{ site.baseurl }}/layout/grid/), and then some. Please read the [default grid system docs]({{ site.baseurl }}/layout/grid/) before proceeding through this page. Features that are covered there are only summarized here. Please note that **Internet Explorer 9 does not support flexbox**, so proceed with caution when enabling it.
 
 {% callout warning %}
 **Heads up!** This flexbox grid documentation is powered by an additional CSS file that overrides our default grid system's CSS. This is only available in our hosted docs and is disabled in development.
@@ -21,7 +22,7 @@ Bootstrap's flexbox grid includes support for every feature from our [default gr
 
 The flexbox grid system behaves similar to our default grid system, but with a few notable differences:
 
-- [Grid mixins](/layout/grid#sass-mixins) and [predefined classes](/layout/grid#predefined-classes) include support for flexbox. Just [enable flexbox support](/getting-started/flexbox) to utilize them as you would otherwise.
+- [Grid mixins]({{ site.baseurl }}/layout/grid#sass-mixins) and [predefined classes]({{ site.baseurl }}/layout/grid#predefined-classes) include support for flexbox. Just [enable flexbox support]({{ site.baseurl }}/getting-started/flexbox/) to utilize them as you would otherwise.
 - Nesting, offsets, pushes, and pulls are all supported in the flexbox grid system.
 - Flexbox grid columns without a set width will automatically layout with equal widths. For example, four columns will each automatically be 25% wide.
 - Flexbox grid columns have significantly more alignment options available, including vertical alignment.
@@ -59,7 +60,7 @@ When flexbox support is enabled, you can utilize breakpoint-specific column clas
 {% endexample %}
 </div>
 
-Auto-layout for flexbox grid columns also means you can set the width of one column and the others will automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths.
+Auto-layout for flexbox grid columns also means you can set the width of one column and the others will automatically resize around it. You may use predefined grid classes (as shown below), grid mixins, or inline widths. Note that the other columns will resize no matter the width of the center column.
 
 <div class="bd-example-row">
 {% example html %}
@@ -75,6 +76,17 @@ Auto-layout for flexbox grid columns also means you can set the width of one col
       3 of 3
     </div>
   </div>
+  <div class="row">
+    <div class="col-xs">
+      1 of 3
+    </div>
+    <div class="col-xs-5">
+      2 of 3 (wider)
+    </div>
+    <div class="col-xs">
+      3 of 3
+    </div>
+  </div>
 </div>
 {% endexample %}
 </div>
@@ -210,3 +222,25 @@ Flexbox utilities for horizontal alignment also exist for a number of layout opt
 </div>
 {% endexample %}
 </div>
+
+## Reordering
+
+Flexbox utilities for controlling the **visual order** of your content.
+
+<div class="bd-example-row">
+{% example html %}
+<div class="container">
+  <div class="row">
+    <div class="col-xs flex-xs-unordered">
+      First, but unordered
+    </div>
+    <div class="col-xs flex-xs-last">
+      Second, but last
+    </div>
+    <div class="col-xs flex-xs-first">
+      Third, but first
+    </div>
+  </div>
+</div>
+{% endexample %}
+</div>
diff --git a/docs/layout/grid.md b/docs/layout/grid.md
index 7114da4b7..55607e464 100644
--- a/docs/layout/grid.md
+++ b/docs/layout/grid.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Grid system
+description: Documentation and examples for using Bootstrap's powerful, responsive, and mobile-first grid system.
 group: layout
 ---
 
@@ -63,11 +64,11 @@ See how aspects of the Bootstrap grid system work across multiple devices with a
         <th></th>
         <th class="text-xs-center">
           Extra small<br>
-          <small>&lt;544px</small>
+          <small>&lt;576px</small>
         </th>
         <th class="text-xs-center">
           Small<br>
-          <small>&ge;544px</small>
+          <small>&ge;576px</small>
         </th>
         <th class="text-xs-center">
           Medium<br>
@@ -90,11 +91,11 @@ See how aspects of the Bootstrap grid system work across multiple devices with a
         <td colspan="4">Collapsed to start, horizontal above breakpoints</td>
       </tr>
       <tr>
-        <th class="text-nowrap" scope="row">Container width</th>
+        <th class="text-nowrap" scope="row">Max container width</th>
         <td>None (auto)</td>
-        <td>576px</td>
+        <td>540px</td>
         <td>720px</td>
-        <td>940px</td>
+        <td>960px</td>
         <td>1140px</td>
       </tr>
       <tr>
@@ -111,7 +112,7 @@ See how aspects of the Bootstrap grid system work across multiple devices with a
       </tr>
       <tr>
         <th class="text-nowrap" scope="row">Gutter width</th>
-        <td colspan="5">1.875rem / 30px (15px on each side of a column)</td>
+        <td colspan="5">30px (15px on each side of a column)</td>
       </tr>
       <tr>
         <th class="text-nowrap" scope="row">Nestable</th>
@@ -139,13 +140,21 @@ Variables and maps determine the number of columns, the gutter width, and the me
 
 {% highlight scss %}
 $grid-columns:      12;
-$grid-gutter-width: 30px;
+$grid-gutter-width-base: 30px;
+
+$grid-gutter-widths: (
+  xs: $grid-gutter-width-base, // 30px
+  sm: $grid-gutter-width-base, // 30px
+  md: $grid-gutter-width-base, // 30px
+  lg: $grid-gutter-width-base, // 30px
+  xl: $grid-gutter-width-base  // 30px
+)
 
 $grid-breakpoints: (
   // Extra small screen / phone
   xs: 0,
   // Small screen / phone
-  sm: 544px,
+  sm: 576px,
   // Medium screen / tablet
   md: 768px,
   // Large screen / desktop
@@ -155,9 +164,9 @@ $grid-breakpoints: (
 );
 
 $container-max-widths: (
-  sm: 576px,
+  sm: 540px,
   md: 720px,
-  lg: 940px,
+  lg: 960px,
   xl: 1140px
 );
 {% endhighlight %}
@@ -168,23 +177,27 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
 
 {% highlight scss %}
 // Creates a wrapper for a series of columns
-@mixin make-row($gutter: $grid-gutter-width) {
+@mixin make-row($gutters: $grid-gutter-widths) {
   @if $enable-flex {
     display: flex;
     flex-wrap: wrap;
   } @else {
     @include clearfix();
   }
-  margin-left:  ($gutter / -2);
-  margin-right: ($gutter / -2);
+
+  @each $breakpoint in map-keys($gutters) {
+    @include media-breakpoint-up($breakpoint) {
+      $gutter: map-get($gutters, $breakpoint);
+      margin-right: ($gutter / -2);
+      margin-left:  ($gutter / -2);
+    }
+  }
 }
 
 // Make the element grid-ready (applying everything but the width)
-@mixin make-col-ready($size, $columns: $grid-columns, $gutter: $grid-gutter-width) {
+@mixin make-col-ready($gutters: $grid-gutter-widths) {
   position: relative;
   min-height: 1px; // Prevent collapsing
-  padding-right: ($gutter / 2);
-  padding-left:  ($gutter / 2);
 
   // Prevent columns from becoming too narrow when at smaller grid tiers by
   // always setting `width: 100%;`. This works because we use `flex` values
@@ -192,9 +205,17 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
   @if $enable-flex {
     width: 100%;
   }
+
+  @each $breakpoint in map-keys($gutters) {
+    @include media-breakpoint-up($breakpoint) {
+      $gutter: map-get($gutters, $breakpoint);
+      padding-right: ($gutter / 2);
+      padding-left:  ($gutter / 2);
+    }
+  }
 }
 
-@mixin make-col($size, $columns: $grid-columns, $gutter: $grid-gutter-width) {
+@mixin make-col($size, $columns: $grid-columns) {
   @if $enable-flex {
     flex: 0 0 percentage($size / $columns);
     // Add a `max-width` to ensure content within each column does not blow out
@@ -208,14 +229,16 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
 }
 
 // Get fancy by offsetting, or changing the sort order
-@mixin make-col-offset($columns) {
-  margin-left: percentage(($columns / $grid-columns));
+@mixin make-col-offset($size, $columns: $grid-columns) {
+  margin-left: percentage($size / $columns);
 }
-@mixin make-col-push($columns) {
-  left: percentage(($columns / $grid-columns));
+
+@mixin make-col-push($size, $columns: $grid-columns) {
+  left: if($size > 0, percentage($size / $columns), auto);
 }
-@mixin make-col-pull($columns) {
-  right: percentage(($columns / $grid-columns));
+
+@mixin make-col-pull($size, $columns: $grid-columns) {
+  right: if($size > 0, percentage($size / $columns), auto);
 }
 {% endhighlight %}
 
@@ -223,7 +246,7 @@ Mixins are used in conjunction with the grid variables to generate semantic CSS
 
 You can modify the variables to your own custom values, or just use the mixins with their default values. Here's an example of using the default settings to create a two-column layout with a gap between.
 
-See it in action in <a href="http://jsbin.com/ruxona/edit">this rendered example</a>.
+See it in action in <a href="https://jsbin.com/ruxona/edit?html,output">this rendered example</a>.
 
 {% highlight scss %}
 .container {
@@ -461,11 +484,18 @@ Using our built-in grid Sass variables and maps, it's possible to completely cus
 
 ### Columns and gutters
 
-The number of grid columns and their horizontal padding (aka, gutters) can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-width` is divided evenly across `padding-left` and `padding-right` for the column gutters.
+The number of grid columns and their horizontal padding (aka, gutters) can be modified via Sass variables. `$grid-columns` is used to generate the widths (in percent) of each individual column while `$grid-gutter-widths` allows breakpoint-specific widths that are divided evenly across `padding-left` and `padding-right` for the column gutters.
 
 {% highlight scss %}
-$grid-columns: 12;
-$grid-gutter-width: 30px;
+$grid-columns:               12 !default;
+$grid-gutter-width-base:     30px !default;
+$grid-gutter-widths: (
+  xs: $grid-gutter-width-base,
+  sm: $grid-gutter-width-base,
+  md: $grid-gutter-width-base,
+  lg: $grid-gutter-width-base,
+  xl: $grid-gutter-width-base
+) !default;
 {% endhighlight %}
 
 ### Grid tiers
@@ -482,7 +512,7 @@ $grid-breakpoints: (
 $container-max-widths: (
   sm: 420px,
   md: 720px,
-  lg: 940px
+  lg: 960px
 );
 {% endhighlight %}
 
diff --git a/docs/layout/media-object.md b/docs/layout/media-object.md
index 602bd210a..b998490d3 100644
--- a/docs/layout/media-object.md
+++ b/docs/layout/media-object.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Media object
+description: Documentation and examples for Bootstrap's media object to construct highly repetitive components like blog comments, tweets, and the like.
 group: layout
 ---
 
@@ -45,7 +46,7 @@ Media components can also be nested.
   <div class="media-body">
     <h4 class="media-heading">Media heading</h4>
     Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.
-    <div class="media">
+    <div class="media mt-2">
       <a class="media-left" href="#">
         <img class="media-object" data-src="holder.js/64x64" alt="Generic placeholder image">
       </a>
@@ -123,7 +124,7 @@ With a bit of extra markup, you can use media inside list (useful for comment th
       <h4 class="media-heading">Media heading</h4>
       <p>Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis.</p>
       <!-- Nested media object -->
-      <div class="media">
+      <div class="media mt-2">
         <a class="media-left" href="#">
           <img class="media-object" data-src="holder.js/64x64" alt="Generic placeholder image">
         </a>
@@ -131,7 +132,7 @@ With a bit of extra markup, you can use media inside list (useful for comment th
           <h4 class="media-heading">Nested media heading</h4>
           Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis.
           <!-- Nested media object -->
-          <div class="media">
+          <div class="media mt-2">
             <div class="media-left">
               <a href="#">
                 <img class="media-object" data-src="holder.js/64x64" alt="Generic placeholder image">
@@ -145,7 +146,7 @@ With a bit of extra markup, you can use media inside list (useful for comment th
         </div>
       </div>
       <!-- Nested media object -->
-      <div class="media">
+      <div class="media mt-2">
         <div class="media-left">
           <a href="#">
             <img class="media-object" data-src="holder.js/64x64" alt="Generic placeholder image">
@@ -158,7 +159,7 @@ With a bit of extra markup, you can use media inside list (useful for comment th
       </div>
     </div>
   </li>
-  <li class="media">
+  <li class="media mt-2">
     <div class="media-body">
       <h4 class="media-heading">Media heading</h4>
       Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis.
diff --git a/docs/layout/overview.md b/docs/layout/overview.md
index 81cdecf60..3e6c7e7e0 100644
--- a/docs/layout/overview.md
+++ b/docs/layout/overview.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Overview
+description: Components and options for laying out your Bootstrap project, including wrapping containers, a powerful grid system, a flexible media object, and responsive utility classes.
 group: layout
 redirect_from: "/layout/"
 ---
diff --git a/docs/layout/responsive-utilities.md b/docs/layout/responsive-utilities.md
index 2a44fd589..4334eb4d6 100644
--- a/docs/layout/responsive-utilities.md
+++ b/docs/layout/responsive-utilities.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Responsive utilities
+description: Use responsive display utility classes for showing and hiding content by device, via media query.
 group: layout
 ---