From c72cc98bd56fb50259c84a1fced38751009eb930 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sat, 27 May 2017 23:01:14 -0700 Subject: [PATCH] update components docs --- docs/components/alerts.md | 8 +------- docs/components/badge.md | 21 ++++++++++++--------- docs/components/breadcrumb.md | 4 ++-- docs/components/button-group.md | 25 +++++++++---------------- docs/components/buttons.md | 8 +------- docs/components/card.md | 8 +++----- docs/components/carousel.md | 8 +++----- docs/components/collapse.md | 8 +------- docs/components/dropdowns.md | 12 ++++-------- docs/components/forms.md | 10 ++-------- docs/components/input-group.md | 10 ++-------- docs/components/jumbotron.md | 2 -- docs/components/list-group.md | 11 +++-------- docs/components/modal.md | 10 ++-------- docs/components/navbar.md | 12 +++--------- docs/components/navs.md | 12 ++++-------- docs/components/pagination.md | 10 ++-------- docs/components/popovers.md | 10 ++-------- docs/components/progress.md | 28 +++++++++------------------- docs/components/scrollspy.md | 10 ++-------- docs/components/tooltips.md | 10 ++-------- 21 files changed, 69 insertions(+), 168 deletions(-) diff --git a/docs/components/alerts.md b/docs/components/alerts.md index dae4ec7d36..3acfd2a797 100644 --- a/docs/components/alerts.md +++ b/docs/components/alerts.md @@ -3,15 +3,9 @@ layout: docs title: Alerts description: Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. group: components +toc: true --- -Provide contextual feedback messages for typical user actions with the handful of available and flexible alert messages. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Examples Alerts are available for any length of text, as well as an optional dismiss button. For proper styling, use one of the four **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts jQuery plugin](#dismissing). diff --git a/docs/components/badge.md b/docs/components/badge.md index a7497a285d..764e5a1cbb 100644 --- a/docs/components/badge.md +++ b/docs/components/badge.md @@ -3,27 +3,30 @@ layout: docs title: Badges description: Documentation and examples for badges, our small count and labeling component. group: components +toc: true --- -Small and adaptive tag for adding context to just about any content. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Example Badges scale to match the size of the immediate parent element by using relative font sizing and `em` units. -{% example html %} +
+
Example heading New
+
Example heading New
+
Example heading New
+
Example heading New
+
Example heading New
+
Example heading New
+
+ +{% highlight html %}

Example heading New

Example heading New

Example heading New

Example heading New

Example heading New
Example heading New
-{% endexample %} +{% endhighlight %} ## Contextual variations diff --git a/docs/components/breadcrumb.md b/docs/components/breadcrumb.md index 8beaa0ae4a..eb286d8471 100644 --- a/docs/components/breadcrumb.md +++ b/docs/components/breadcrumb.md @@ -1,11 +1,11 @@ --- layout: docs title: Breadcrumb -description: Indicate the current page's location within a navigational hierarchy. +description: Indicate the current page's location within a navigational hierarchy that automatically adds separators via CSS. group: components --- -Indicate the current page's location within a navigational hierarchy. Separators are automatically added in CSS through [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`content`](https://developer.mozilla.org/en-US/docs/Web/CSS/content). +Separators are automatically added in CSS through [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`content`](https://developer.mozilla.org/en-US/docs/Web/CSS/content). {% example html %}
    diff --git a/docs/components/button-group.md b/docs/components/button-group.md index d2d5140ed1..f328b94227 100644 --- a/docs/components/button-group.md +++ b/docs/components/button-group.md @@ -3,26 +3,12 @@ layout: docs title: Button group description: Group a series of buttons together on a single line with the button group, and super-power them with JavaScript. group: components +toc: true --- -Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin]({{ site.baseurl }}/components/buttons/#button-plugin). - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -{% callout warning %} -## Ensure correct `role` and provide a label - -In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`. - -In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct role attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used. -{% endcallout %} - ## Basic example -Wrap a series of buttons with `.btn` in `.btn-group`. +Wrap a series of buttons with `.btn` in `.btn-group`. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin]({{ site.baseurl }}/components/buttons/#button-plugin). {% example html %}
    @@ -32,6 +18,13 @@ Wrap a series of buttons with `.btn` in `.btn-group`.
    {% endexample %} +{% callout warning %} +#### Ensure correct `role` and provide a label + +In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, an appropriate `role` attribute needs to be provided. For button groups, this would be `role="group"`, while toolbars should have a `role="toolbar"`. + +In addition, groups and toolbars should be given an explicit label, as most assistive technologies will otherwise not announce them, despite the presence of the correct role attribute. In the examples provided here, we use `aria-label`, but alternatives such as `aria-labelledby` can also be used. +{% endcallout %} ## Button toolbar Combine sets of button groups into button toolbars for more complex components. Use utility classes as needed to space out groups, buttons, and more. diff --git a/docs/components/buttons.md b/docs/components/buttons.md index 7f701d90a3..cfd243dad0 100644 --- a/docs/components/buttons.md +++ b/docs/components/buttons.md @@ -4,15 +4,9 @@ title: Buttons description: Use Bootstrap's custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more. group: components redirect_from: "/components/" +toc: true --- -Use Bootstrap's custom button styles for actions in forms, dialogs, and more. Includes support for a handful of contextual variations, sizes, states, and more. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Examples Bootstrap includes six predefined button styles, each serving its own semantic purpose. diff --git a/docs/components/card.md b/docs/components/card.md index 74debae448..ff3096ec2b 100644 --- a/docs/components/card.md +++ b/docs/components/card.md @@ -3,17 +3,15 @@ layout: docs title: Cards description: Bootstrap's cards provide a flexible and extensible content container with multiple variants and options. group: components +toc: true --- +## About + A **card** is a flexible and extensible content container. It includes options for headers and footers, a wide variety of content, contextual background colors, and powerful display options. If you're familiar with Bootstrap 3, cards replace our old panels, wells, and thumbnails. Similar functionality to those components is available as modifier classes for cards. -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Example Cards are built with as little markup and styles as possible, but still manage to deliver a ton of control and customization. Built with flexbox, they offer easy alignment and mix well with other Bootstrap components. diff --git a/docs/components/carousel.md b/docs/components/carousel.md index af00dc526c..ae82eb08f5 100644 --- a/docs/components/carousel.md +++ b/docs/components/carousel.md @@ -3,19 +3,17 @@ layout: docs title: Carousel description: A slideshow component for cycling through elements—images or slides of text—like a carousel. group: components +toc: true --- +## How it works + The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.). Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Example Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. diff --git a/docs/components/collapse.md b/docs/components/collapse.md index 65b8171bdc..84262487b3 100644 --- a/docs/components/collapse.md +++ b/docs/components/collapse.md @@ -3,15 +3,9 @@ layout: docs title: Collapse description: Toggle the visibility of content across your project with a few classes and our JavaScript plugins. group: components +toc: true --- -The Bootstrap collapse plugin allows you to toggle content on your pages with a few classes thanks to some helpful JavaScript. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Example Click the buttons below to show and hide another element via class changes: diff --git a/docs/components/dropdowns.md b/docs/components/dropdowns.md index 13f49a32f4..306fb7f2b9 100644 --- a/docs/components/dropdowns.md +++ b/docs/components/dropdowns.md @@ -3,18 +3,14 @@ layout: docs title: Dropdowns description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin. group: components +toc: true --- -Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/) - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Overview -Things to know when using the popover plugin: +Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/) + +Things to know when using the dropdown plugin: - Dropdown rely on the 3rd party library [Popper.js](https://popper.js.org) for positioning. You must include [popper.min.js](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.9.9/umd/popper.min.js) before bootstrap.js in order for dropdowns to work! - Popper.js handle natively the flip of Dropdown when it's outside the viewport, if you want to disable that's behavior use `flip` attribute diff --git a/docs/components/forms.md b/docs/components/forms.md index 52230fa54e..b2546a72b6 100644 --- a/docs/components/forms.md +++ b/docs/components/forms.md @@ -1,17 +1,11 @@ --- layout: docs title: Forms -description: Examples and usage guidelines for form controls, form layouts, and custom forms. +description: Examples and usage guidelines for form control styles, layout options, and custom components for creating a wide variety of forms. group: components +toc: true --- -Bootstrap provides several form control styles, layout options, and custom components for creating a wide variety of forms. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Form controls Bootstrap's form controls expand on [our Rebooted form styles]({{ site.baseurl }}/content/reboot/#forms) with classes. Use these classes to opt into their customized displays for a more consistent rendering across browsers and devices. The example form below demonstrates common HTML form elements that receive updated styles from Bootstrap with additional classes. diff --git a/docs/components/input-group.md b/docs/components/input-group.md index f84cb24531..144d6f6284 100644 --- a/docs/components/input-group.md +++ b/docs/components/input-group.md @@ -1,17 +1,11 @@ --- layout: docs title: Input group -description: Extend form controls with the input group. +description: Easily extend form controls by adding text, buttons, or button groups on either side of textual inputs. group: components +toc: true --- -Easily extend form controls by adding text, buttons, or button groups on either side of textual ``s. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Basic example Place one add-on or button on either side of an input. You may also place one on both sides of an input. **We do not support multiple form-controls in a single input group.** diff --git a/docs/components/jumbotron.md b/docs/components/jumbotron.md index 49b7ba9a35..2d52784129 100644 --- a/docs/components/jumbotron.md +++ b/docs/components/jumbotron.md @@ -7,8 +7,6 @@ group: components A lightweight, flexible component that can optionally extend the entire viewport to showcase key marketing messages on your site. -## Example - {% example html %}

    Hello, world!

    diff --git a/docs/components/list-group.md b/docs/components/list-group.md index dcf605aeeb..f67f3c86e7 100644 --- a/docs/components/list-group.md +++ b/docs/components/list-group.md @@ -1,18 +1,13 @@ --- layout: docs title: List group -description: Learn about Bootstrap's list group component for rendering series of related content. +description: List groups are a flexible and powerful component for displaying a series of content. Modify and extend them to support just about any content within. group: components +toc: true --- -List groups are a flexible and powerful component for displaying a series of content. List group items can be modified and extended to support just about any content within. They can also be used as navigation with the right modifier class. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Basic example + The most basic list group is an unordered list with list items and the proper classes. Build upon it with the options that follow, or with your own CSS as needed. {% example html %} diff --git a/docs/components/modal.md b/docs/components/modal.md index a2f4471d3c..8abb6a9c24 100644 --- a/docs/components/modal.md +++ b/docs/components/modal.md @@ -1,17 +1,11 @@ --- layout: docs title: Modal -description: Learn how to use Bootstrap's modals to add dialog prompts to your site. +description: Use Bootstrap's JavaScript modal plugin to add dialogs to your site for lightboxes, user notifications, or completely custom content. group: components +toc: true --- -Modals are streamlined, but flexible dialog prompts powered by JavaScript. They support a number of use cases from user notification to completely custom content and feature a handful of helpful subcomponents, sizes, and more. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## How it works Before getting started with Bootstrap's modal component, be sure to read the following as our menu options have recently changed. diff --git a/docs/components/navbar.md b/docs/components/navbar.md index 0891d2327d..07c86c938c 100644 --- a/docs/components/navbar.md +++ b/docs/components/navbar.md @@ -1,17 +1,11 @@ --- layout: docs title: Navbar -description: Documentation and examples for Bootstrap's powerful, responsive navigation header. +description: Documentation and examples for Bootstrap's powerful, responsive navigation header, the navbar. Includes support for branding, navigation, and more, including support for our collapse plugin. group: components +toc: true --- -The navbar is a wrapper that positions branding, navigation, and other elements in a concise header. It's easily extensible and, thanks to our Collapse plugin, can easily integrate responsive behaviors. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## How it works Here's what you need to know before getting started with the navbar: @@ -76,7 +70,7 @@ The `.navbar-brand` can be applied to most elements, but an anchor works best as {% endexample %} diff --git a/docs/components/navs.md b/docs/components/navs.md index 5c3f2cf9da..2e340287df 100644 --- a/docs/components/navs.md +++ b/docs/components/navs.md @@ -3,17 +3,13 @@ layout: docs title: Navs description: Documentation and examples for how to use Bootstrap's included navigation components. group: components +toc: true --- -Navigation available in Bootstrap share general markup and styles, from the base `.nav` class to the active and disabled states. Swap modifier classes to switch between each style. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Base nav +Navigation available in Bootstrap share general markup and styles, from the base `.nav` class to the active and disabled states. Swap modifier classes to switch between each style. + The base `.nav` component is built with flexbox and provide a strong foundation for building all types of navigation components. It includes some style overrides (for working with lists), some link padding for larger hit areas, and basic disabled styling. {% callout info %} @@ -297,7 +293,7 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin {% endexample %} -## JavaScript behavior for dynamic tabbed interfaces +## JavaScript behavior 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. diff --git a/docs/components/pagination.md b/docs/components/pagination.md index 03c3a56ece..0ea749e301 100644 --- a/docs/components/pagination.md +++ b/docs/components/pagination.md @@ -1,17 +1,11 @@ --- layout: docs title: Pagination -description: Documentation and examples for showing pagination links. +description: Documentation and examples for showing pagination to indicate a series of related content exists across multiple pages. group: components +toc: true --- -Pagination links indicate a series of related content exists across multiple pages. Typically these are used where a multi-page approach to long lists of content improves general performance, such as in search results or inboxes. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Overview We use a large block of connected links for our pagination, making links hard to miss and easily scalable—all while providing large hit areas. Pagination is built with list HTML elements so screen readers can announce the number of available links. Use a wrapping `
    {% endexample %} -## Customizing - -Customize the appearance of your progress bars with custom CSS, background utilities, stripes, and more. - -### Labels +## Labels Add labels to your progress bars by placing text within the `.progress-bar`. @@ -63,7 +53,7 @@ Add labels to your progress bars by placing text within the `.progress-bar`. {% endexample %} -### Height +## Height We only set a `height` value on the `.progress-bar`, so if you change that value the outer `.progress` will automatically resize accordingly. @@ -76,7 +66,7 @@ We only set a `height` value on the `.progress-bar`, so if you change that value {% endexample %} -### Backgrounds +## Backgrounds Use background utility classes to change the appearance of individual progress bars. @@ -95,7 +85,7 @@ Use background utility classes to change the appearance of individual progress b {% endexample %} -### Multiple bars +## Multiple bars Include multiple progress bars in a progress component if you need. @@ -107,7 +97,7 @@ Include multiple progress bars in a progress component if you need. {% endexample %} -### Striped +## Striped Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gradient over the progress bar's background color. @@ -129,7 +119,7 @@ Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gra {% endexample %} -### Animated stripes +## Animated stripes The striped gradient can also be animated. Add `.progress-bar-animated` to `.progress-bar` to animate the stripes right to left via CSS3 animations. diff --git a/docs/components/scrollspy.md b/docs/components/scrollspy.md index 80c0571618..a2829d3e53 100644 --- a/docs/components/scrollspy.md +++ b/docs/components/scrollspy.md @@ -1,17 +1,11 @@ --- layout: docs title: Scrollspy -description: Documentation and examples for the scrollspy plugin with Bootstrap's navigation components. +description: Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport. group: components +toc: true --- -Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## How it works Scrollspy has a few requirements to function properly: diff --git a/docs/components/tooltips.md b/docs/components/tooltips.md index 2e630e93eb..baee524518 100644 --- a/docs/components/tooltips.md +++ b/docs/components/tooltips.md @@ -1,17 +1,11 @@ --- layout: docs title: Tooltips -description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript. +description: Documentation and examples for adding custom Bootstrap tooltips with CSS and JavaScript using CSS3 for animations and data-attributes for local title storage. group: components +toc: true --- -Inspired by the excellent Tipsy jQuery plugin written by Jason Frame. Tooltips are an updated version, which don't rely on images, use CSS3 for animations, and data-attributes for local title storage. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - ## Overview Things to know when using the tooltip plugin: -- 2.47.2