rewrite helpers in markdown

1 files changed, 121 insertions, 81 deletions

diff --git a/docs/_includes/css/helpers.md b/docs/_includes/css/helpers.md
index dc992ee23..24f9a027a 100644
--- a/docs/_includes/css/helpers.md
+++ b/docs/_includes/css/helpers.md
@@ -1,65 +1,78 @@
-<div class="bs-docs-section">
-  <h1 id="helper-classes" class="page-header">Helper classes</h1>
-
-  <h3 id="helper-classes-colors">Contextual colors</h3>
-  <p>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.</p>
-  <div class="bs-example">
-    <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>
-    <p class="text-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
-    <p class="text-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
-    <p class="text-warning">Etiam porta sem malesuada magna mollis euismod.</p>
-    <p class="text-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
-  </div>
-{% highlight html %}
-<p class="text-muted">...</p>
-<p class="text-primary">...</p>
-<p class="text-success">...</p>
-<p class="text-info">...</p>
-<p class="text-warning">...</p>
-<p class="text-danger">...</p>
-{% endhighlight %}
-  <div class="bs-callout bs-callout-info">
-    <h4>Dealing with specificity</h4>
-    <p>Sometimes emphasis classes cannot be applied due to the specificity of another selector. In most cases, a sufficient workaround is to wrap your text in a <code>&lt;span&gt;</code> with the class.</p>
-  </div>
-
-  <h3 id="helper-classes-backgrounds">Contextual backgrounds</h3>
-  <p>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.</p>
-  <div class="bs-example bs-example-bg-classes">
-    <p class="bg-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</p>
-    <p class="bg-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
-    <p class="bg-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
-    <p class="bg-warning">Etiam porta sem malesuada magna mollis euismod.</p>
-    <p class="bg-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
-  </div>
-{% highlight html %}
-<p class="bg-primary">...</p>
-<p class="bg-success">...</p>
-<p class="bg-info">...</p>
-<p class="bg-warning">...</p>
-<p class="bg-danger">...</p>
-{% endhighlight %}
-  <div class="bs-callout bs-callout-info">
-    <h4>Dealing with specificity</h4>
-    <p>Sometimes contextual background classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a <code>&lt;div&gt;</code> with the class.</p>
-  </div>
-
-  <h3 id="helper-classes-close">Close icon</h3>
-  <p>Use the generic close icon for dismissing content like modals and alerts.</p>
-  <div class="bs-example">
-    <p><button type="button" class="close"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button></p>
-  </div>
-{% highlight html %}
-<button type="button" class="close"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
-{% endhighlight %}
+<a id="helpers"></a>
 
-  <h3 id="helper-classes-floats">Quick floats</h3>
-  <p>Float an element to the left or right with a class. <code>!important</code> is included to avoid specificity issues. Classes can also be used as mixins.</p>
-{% highlight html %}
+# Helper classes
+
+
+
+<a id="helpers-colors"></a>
+
+### Contextual colors
+
+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>
+<p class="text-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
+<p class="text-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
+<p class="text-warning">Etiam porta sem malesuada magna mollis euismod.</p>
+<p class="text-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
+{% endexample %}
+
+<div class="bs-callout bs-callout-info">
+  <h4>Dealing with specificity</h4>
+  <p>Sometimes emphasis classes cannot be applied due to the specificity of another selector. In most cases, a sufficient workaround is to wrap your text in a <code>&lt;span&gt;</code> with the class.</p>
+</div>
+
+
+
+<a id="helpers-bgs"></a>
+
+### Contextual backgrounds
+
+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.
+
+{% example html %}
+<div class="bg-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</div>
+<div class="bg-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</div>
+<div class="bg-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</div>
+<div class="bg-warning">Etiam porta sem malesuada magna mollis euismod.</div>
+<div class="bg-danger">Donec ullamcorper nulla non metus auctor fringilla.</div>
+{% endexample %}
+
+<div class="bs-callout bs-callout-info">
+  <h4>Dealing with specificity</h4>
+  <p>Sometimes contextual background classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a <code>&lt;div&gt;</code> with the class.</p>
+</div>
+
+
+
+<a id="helpers-close"></a>
+
+### Close icon
+
+Use a generic close icon for dismissing content like modals and alerts. **Be sure to include screen reader text when you can** as we've done with `.sr-only`.
+
+{% example html %}
+<button type="button" class="close">
+  <span aria-hidden="true">&times;</span>
+  <span class="sr-only">Close</span>
+</button>
+{% endexample %}
+
+
+
+<a id="helpers-floats"></a>
+
+### Quick floats
+
+Float an element to the left or right with a class. `!important` is included to avoid specificity issues. Classes can also be used as mixins.
+
+{% example html %}
 <div class="pull-left">...</div>
 <div class="pull-right">...</div>
-{% endhighlight %}
+{% endexample %}
+
 {% highlight scss %}
 // Classes
 .pull-left {
@@ -78,17 +91,23 @@
 }
 {% endhighlight %}
 
-  <div class="bs-callout bs-callout-warning">
-    <h4>Not for use in navbars</h4>
-    <p>To align components in navbars with utility classes, use <code>.navbar-left</code> or <code>.navbar-right</code> instead. <a href="../components/#navbar-component-alignment">See the navbar docs</a> for details.</p>
-  </div>
+<div class="bs-callout bs-callout-warning">
+  <h4>Not for use in navbars</h4>
+  <p>To align components in navbars with utility classes, use <code>.navbar-left</code> or <code>.navbar-right</code> instead. <a href="../components/#navbar-component-alignment">See the navbar docs</a> for details.</p>
+</div>
 
 
-  <h3 id="helper-classes-center">Center content blocks</h3>
-  <p>Set an element to <code>display: block</code> and center via <code>margin</code>. Available as a mixin and class.</p>
-{% highlight html %}
+
+<a id="helpers-center"></a>
+
+### Center content blocks
+
+Set an element to `display: block;` and center via `margin`. Available as a mixin and class.
+
+{% example html %}
 <div class="center-block">...</div>
-{% endhighlight %}
+{% endexample %}
+
 {% highlight scss %}
 // Classes
 .center-block {
@@ -104,12 +123,15 @@
 {% endhighlight %}
 
 
-  <h3 id="helper-classes-clearfix">Clearfix</h3>
-  <p>Easily clear <code>float</code>s by adding <code>.clearfix</code> <strong>to the parent element</strong>. Utilizes <a href="http://nicolasgallagher.com/micro-clearfix-hack/">the micro clearfix</a> as popularized by Nicolas Gallagher. Can also be used as a mixin.</p>
+
+<a id="helpers-clearfix"></a>
+
+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.
+
 {% highlight html %}
-<!-- Usage as a class -->
 <div class="clearfix">...</div>
 {% endhighlight %}
+
 {% highlight scss %}
 // Mixin itself
 .clearfix() {
@@ -130,13 +152,20 @@
 {% endhighlight %}
 
 
-  <h3 id="helper-classes-show-hide">Showing and hiding content</h3>
-  <p>Force an element to be shown or hidden (<strong>including for screen readers</strong>) with the use of <code>.show</code> and <code>.hidden</code> classes. These classes use <code>!important</code> to avoid specificity conflicts, just like the <a href="#helper-classes-floats">quick floats</a>. They are only available for block level toggling. They can also be used as mixins.</p>
-  <p>Furthermore, <code>.invisible</code> can be used to toggle only the visibility of an element, meaning its <code>display</code> is not modified and the element can still affect the flow of the document.</p>
+
+<a id="helpers-toggles"></a>
+
+### Showing and hiding content
+
+Force an element to be shown or hidden (**including for screen readers**) with the use of `.show` and `.hidden` classes. These classes use `!important` to avoid specificity conflicts, just like the [quick floats](#helper-floats). They are only available for block level toggling. They can also be used as mixins.
+
+Furthermore, `.invisible` can be used to toggle only the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
+
 {% highlight html %}
 <div class="show">...</div>
 <div class="hidden">...</div>
 {% endhighlight %}
+
 {% highlight scss %}
 // Classes
 .show {
@@ -160,11 +189,17 @@
 {% endhighlight %}
 
 
-  <h3 id="helper-classes-screen-readers">Screen reader and keyboard navigation content</h3>
-  <p>Hide an element to all devices <strong>except screen readers</strong> with <code>.sr-only</code>. Combine <code>.sr-only</code> with <code>.sr-only-focusable</code> to show the element again when it's focused (e.g. by a keyboard-only user). Necessary for following <a href="../getting-started/#accessibility">accessibility best practices</a>. Can also be used as mixins.</p>
+
+<a id="helpers-screen-readers"></a>
+
+### Screen readers and keyboard navigation
+
+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). Necessary for following [accessibility best practices](../getting-started/#accessibility). Can also be used as mixins.
+
 {% highlight html %}
 <a class="sr-only sr-only-focusable" href="#content">Skip to main content</a>
 {% endhighlight %}
+
 {% highlight scss %}
 // Usage as a Mixin
 .skip-navigation {
@@ -174,15 +209,20 @@
 {% endhighlight %}
 
 
-  <h3 id="helper-classes-image-replacement">Image replacement</h3>
-  <p>Utilize the <code>.text-hide</code> class or mixin to help replace an element's text content with a background image.</p>
-{% highlight html %}
+
+<a id="helpers-image-replacement"></a>
+
+### Image replacement
+
+Utilize the `.text-hide` class or mixin to help replace an element's text content with a background image.
+
+{% example html %}
 <h1 class="text-hide">Custom heading</h1>
-{% endhighlight %}
-  {% highlight scss %}
+{% endexample %}
+
+{% highlight scss %}
 // Usage as a Mixin
 .heading {
   .text-hide();
 }
 {% endhighlight %}
-</div>