From f682dec5c25f4ff1a29b34e10d339d549359cdb2 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sun, 28 May 2017 11:25:59 -0700
Subject: [PATCH] new toc in utils and about and extend

---
 docs/about/brand.md                  |  1 +
 docs/extend/icons.md                 |  1 +
 docs/utilities/borders.md            |  4 ++--
 docs/utilities/clearfix.md           |  2 ++
 docs/utilities/close-icon.md         |  4 +++-
 docs/utilities/colors.md             |  4 ++--
 docs/utilities/display.md            |  9 ++-------
 docs/utilities/flexbox.md            |  9 ++-------
 docs/utilities/image-replacement.md  |  2 ++
 docs/utilities/position.md           | 10 +++++-----
 docs/utilities/responsive-helpers.md |  4 ++--
 docs/utilities/screenreaders.md      |  2 ++
 docs/utilities/sizing.md             |  6 +++---
 docs/utilities/spacing.md            |  9 ++++-----
 docs/utilities/typography.md         |  9 ++-------
 docs/utilities/vertical-align.md     |  1 +
 docs/utilities/visibility.md         |  1 +
 17 files changed, 37 insertions(+), 41 deletions(-)

diff --git a/docs/about/brand.md b/docs/about/brand.md
index 32c40b9c4d..5fdc06eb5c 100644
--- a/docs/about/brand.md
+++ b/docs/about/brand.md
@@ -3,6 +3,7 @@ layout: docs
 title: Brand guidelines
 description: Documentation and examples for Bootstrap's logo and brand usage guidelines.
 group: about
+toc: true
 ---
 
 Have a need for Bootstrap's brand resources? Great! We have only a few guidelines we follow, and in turn ask you to follow as well. These guidelines were inspired by MailChimp's [Brand Assets](https://mailchimp.com/about/brand-assets/).
diff --git a/docs/extend/icons.md b/docs/extend/icons.md
index c619ed2cea..3b4aea3eb2 100644
--- a/docs/extend/icons.md
+++ b/docs/extend/icons.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Icons
+description: Guidance and suggestions for using external icon libraries with Bootstrap.
 group: extend
 ---
 
diff --git a/docs/utilities/borders.md b/docs/utilities/borders.md
index 1f092c36af..8bf3f46740 100644
--- a/docs/utilities/borders.md
+++ b/docs/utilities/borders.md
@@ -1,12 +1,12 @@
 ---
 layout: docs
 title: Borders
+description: Use border utilities to quickly style the border and border-radius of an element. Great for images, buttons, or any other element.
 group: utilities
 redirect_from: "/utilities/"
+toc: true
 ---
 
-Use border utilities to quickly style the `border` and `border-radius` of an element. Great for images, buttons, or any other element.
-
 ## Border
 
 Add classes to an element to remove all borders or some borders.
diff --git a/docs/utilities/clearfix.md b/docs/utilities/clearfix.md
index 49410df098..5b5727b117 100644
--- a/docs/utilities/clearfix.md
+++ b/docs/utilities/clearfix.md
@@ -1,7 +1,9 @@
 ---
 layout: docs
 title: Clearfix
+description: Quickly and easily clear floated content within a container by adding a clearfix utility.
 group: utilities
+toc: true
 ---
 
 Easily clear `float`s by adding `.clearfix` **to the parent element**. Utilizes [the micro clearfix](http://nicolasgallagher.com/micro-clearfix-hack/) as popularized by Nicolas Gallagher. Can also be used as a mixin.
diff --git a/docs/utilities/close-icon.md b/docs/utilities/close-icon.md
index 5ec456bccd..4619132de5 100644
--- a/docs/utilities/close-icon.md
+++ b/docs/utilities/close-icon.md
@@ -1,10 +1,12 @@
 ---
 layout: docs
 title: Close icon
+description: Use a generic close icon for dismissing content like modals and alerts.
 group: utilities
+toc: true
 ---
 
-Use a generic close icon for dismissing content like modals and alerts. **Be sure to include text for screen readers**, as we've done with `aria-label`.
+**Be sure to include text for screen readers**, as we've done with `aria-label`.
 
 {% example html %}
 <button type="button" class="close" aria-label="Close">
diff --git a/docs/utilities/colors.md b/docs/utilities/colors.md
index b114d74fe5..80e096cf95 100644
--- a/docs/utilities/colors.md
+++ b/docs/utilities/colors.md
@@ -1,11 +1,11 @@
 ---
 layout: docs
 title: Colors
+description: Convey meaning through color with a handful of color utility classes. Includes support for styling links with hover states, too.
 group: utilities
+toc: true
 ---
 
-Convey meaning through color with a handful of emphasis utility classes. These may also be applied to links and will darken on hover just like our default link styles.
-
 {% example html %}
 <p class="text-muted">Fusce dapibus, tellus ac cursus commodo, tortor mauris nibh.</p>
 <p class="text-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</p>
diff --git a/docs/utilities/display.md b/docs/utilities/display.md
index 27f70e0b2a..86c7411905 100644
--- a/docs/utilities/display.md
+++ b/docs/utilities/display.md
@@ -1,16 +1,11 @@
 ---
 layout: docs
 title: Display property
+description: Quickly and responsively toggle the display value of components and more with our display utilities. Includes support for some of the more common values, as well as some extras for controlling display when printing.
 group: utilities
+toc: true
 ---
 
-Quickly and responsively toggle the `display` value of components and more with our display utilities. Includes support for some of the more common values, as well as some extras for controlling `display` when printing.
-
-## Contents
-
-* Will be replaced with the ToC, excluding the "Contents" header
-{:toc}
-
 ## Common `display` values
 
 The [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) accepts a handful of values and we support many of them with utility classes. We purposefully don't provide every value as a utility, so here's what we support:
diff --git a/docs/utilities/flexbox.md b/docs/utilities/flexbox.md
index 9bca028486..bf2a6f37c0 100644
--- a/docs/utilities/flexbox.md
+++ b/docs/utilities/flexbox.md
@@ -1,16 +1,11 @@
 ---
 layout: docs
 title: Flexbox
+description: Quickly manage the layout, alignment, and sizing of grid columns, navigation, components, and more with a full suite of responsive flexbox utilities. For more complex implementations, custom CSS may be necessary.
 group: utilities
+toc: true
 ---
 
-Quickly manage the layout, alignment, and sizing of grid columns, navigation, components, and more with a full suite of responsive flexbox utilities. For more complex implementations, custom CSS may be necessary.
-
-## Contents
-
-* Will be replaced with the ToC, excluding the "Contents" header
-{:toc}
-
 ## Enable flex behaviors
 
 Apply `display` utilities to create a flexbox container and transform **direct children elements** into flex items. Flex containers and items are able to be modified further with additional flex properties.
diff --git a/docs/utilities/image-replacement.md b/docs/utilities/image-replacement.md
index 720e7b5a92..b11c936c4b 100644
--- a/docs/utilities/image-replacement.md
+++ b/docs/utilities/image-replacement.md
@@ -1,7 +1,9 @@
 ---
 layout: docs
 title: Image replacement
+description: Swap text for background images with the image replacement class.
 group: utilities
+toc: true
 ---
 
 Utilize the `.text-hide` class or mixin to help replace an element's text content with a background image.
diff --git a/docs/utilities/position.md b/docs/utilities/position.md
index 6b8268c488..93f0fd040a 100644
--- a/docs/utilities/position.md
+++ b/docs/utilities/position.md
@@ -1,12 +1,12 @@
 ---
 layout: docs
 title: Position
+description: Use these shorthand utilities for quickly configuring the position of an element.
 group: utilities
+toc: true
 ---
 
-Position utilities are helpful for quickly placing a component outside the normal document flow. Choose from a handful of fixed or sticky position classes as needed.
-
-### Fixed top
+## Fixed top
 
 Position an element at the top of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add aditional CSS.
 
@@ -14,7 +14,7 @@ Position an element at the top of the viewport, from edge to edge. Be sure you u
 <div class="fixed-top">...</div>
 {% endhighlight %}
 
-### Fixed bottom
+## Fixed bottom
 
 Position an element at the bottom of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add aditional CSS.
 
@@ -22,7 +22,7 @@ Position an element at the bottom of the viewport, from edge to edge. Be sure yo
 <div class="fixed-bottom">...</div>
 {% endhighlight %}
 
-### Sticky top
+## Sticky top
 
 Position an element at the top of the viewport, from edge to edge, but only after you scroll past it. The `.sticky-top` utility uses CSS's `position: sticky`, which isn't fully supported in all browsers.
 
diff --git a/docs/utilities/responsive-helpers.md b/docs/utilities/responsive-helpers.md
index 0f1a43ee1e..ae65eff6b4 100644
--- a/docs/utilities/responsive-helpers.md
+++ b/docs/utilities/responsive-helpers.md
@@ -1,13 +1,13 @@
 ---
 layout: docs
 title: Responsive helpers
+description: Create responsive video or slideshow embeds based on the width of the parent by creating an intrinsic ratio that scales on any device.
 group: utilities
+toc: true
 ---
 
 ## Responsive embeds
 
-Allow browsers to determine video or slideshow dimensions based on the width of their containing block by creating an intrinsic ratio that will properly scale on any device.
-
 Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` elements; optionally use an explicit descendant class `.embed-responsive-item` when you want to match the styling for other attributes.
 
 **Pro-Tip!** You don't need to include `frameborder="0"` in your `<iframe>`s as we override that for you.
diff --git a/docs/utilities/screenreaders.md b/docs/utilities/screenreaders.md
index 411f3ddb23..73743b3062 100644
--- a/docs/utilities/screenreaders.md
+++ b/docs/utilities/screenreaders.md
@@ -1,7 +1,9 @@
 ---
 layout: docs
 title: Screenreaders
+description: Use screenreader utilities to hide elements on all devices execept screen readers.
 group: utilities
+toc: true
 ---
 
 Hide an element to all devices **except screen readers** with `.sr-only`. Combine `.sr-only` with `.sr-only-focusable` to show the element again when it's focused (e.g. by a keyboard-only user). Can also be used as mixins.
diff --git a/docs/utilities/sizing.md b/docs/utilities/sizing.md
index eabb4653ac..e2a5ed1979 100644
--- a/docs/utilities/sizing.md
+++ b/docs/utilities/sizing.md
@@ -1,12 +1,12 @@
 ---
 layout: docs
 title: Sizing
+description: Easily make an element as wide or as tall (relative to its parent) with our width and height utilities.
 group: utilities
+toc: true
 ---
 
-Easily make an element as wide or as tall (relative to its parent) with our width and height utilities. Includes support for `25%`, `50%`, `75%`, and `100%` by default.
-
-Width and height utilities are generated from the `$sizes` Sass map in `_variables.scss`. Modify those values as you need to generate different utilities here.
+Width and height utilities are generated from the `$sizes` Sass map in `_variables.scss`. Includes support for `25%`, `50%`, `75%`, and `100%` by default. Modify those values as you need to generate different utilities here.
 
 {% example html %}
 <div class="w-25 p-3" style="background-color: #eee;">Width 25%</div>
diff --git a/docs/utilities/spacing.md b/docs/utilities/spacing.md
index fa8a0d76c9..d6d2d7b540 100644
--- a/docs/utilities/spacing.md
+++ b/docs/utilities/spacing.md
@@ -1,16 +1,15 @@
 ---
 layout: docs
 title: Spacing
+description: Bootstrap includes a wide range of shorthand responsive margin and padding utility classes to modify an element's appearance.
 group: utilities
+toc: true
 ---
 
+## How it works
+
 Assign responsive-friendly `margin` or `padding` values to an element or a subset of its sides with shorthand classes. Includes support for individual properties, all properties, and vertical and horizontal properties. Classes are built from a default Sass map ranging from `.25rem` to `3rem`.
 
-## Contents
-
-* Will be replaced with the ToC, excluding the "Contents" header
-{:toc}
-
 ## Notation
 
 Spacing utilities that apply to all breakpoints, from `xs` to `xl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
diff --git a/docs/utilities/typography.md b/docs/utilities/typography.md
index 5e29fd88cd..32e11335dd 100644
--- a/docs/utilities/typography.md
+++ b/docs/utilities/typography.md
@@ -1,16 +1,11 @@
 ---
 layout: docs
 title: Typography
+description: Documentation and examples for common text utilities to control alignment, wrapping, weight, and more.
 group: utilities
+toc: true
 ---
 
-The following utilities can be used to add additional styles to texts.
-
-## Contents
-
-* Will be replaced with the ToC, excluding the "Contents" header
-{:toc}
-
 ## Text alignment
 
 Easily realign text to components with text alignment classes.
diff --git a/docs/utilities/vertical-align.md b/docs/utilities/vertical-align.md
index 09ae115b08..e684982704 100644
--- a/docs/utilities/vertical-align.md
+++ b/docs/utilities/vertical-align.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Vertical alignment
+description: Easily change the vertical alignment of inlie, inline-block, inline-table, and table cell elements.
 group: utilities
 ---
 
diff --git a/docs/utilities/visibility.md b/docs/utilities/visibility.md
index 5b7d28664b..9e127139fd 100644
--- a/docs/utilities/visibility.md
+++ b/docs/utilities/visibility.md
@@ -1,6 +1,7 @@
 ---
 layout: docs
 title: Visibility
+description: Control the visibility, without modifying the display, of elements with visibility utilities.
 group: utilities
 ---