From b5c5f431e31d38c7becf25fc303188a9ac8364d1 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Mon, 24 Oct 2016 16:05:59 -0700 Subject: copy changes, add toc, tweak ads placement --- docs/getting-started/download.md | 13 ++++++++++--- docs/getting-started/introduction.md | 5 +++-- 2 files changed, 13 insertions(+), 5 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/download.md b/docs/getting-started/download.md index 448afcad3..00e1a1cb6 100644 --- a/docs/getting-started/download.md +++ b/docs/getting-started/download.md @@ -7,18 +7,25 @@ group: getting-started **Bootstrap v{{ site.current_version}}** is available for download in several ways, including some of your favorite package managers. Choose from the options below to snag just what you need. -### Bootstrap CSS and JS +{% include ads.html %} + +## Contents + +* Will be replaced with the ToC, excluding the "Contents" header +{:toc} + +## Bootstrap CSS and JS **Download Bootstrap's ready-to-use code to easily drop into your project.** Includes compiled and minified versions of all our CSS bundles (default, flexbox-enabled, grid only, or Reboot only) and JavaScript plugins. Doesn't include documentation or source files. Download Bootstrap -### Source files +## Source files **Want to compile Bootstrap with your project's asset pipeline?** Choose this option to download our source Sass, JavaScript, and documentation files. Requires a Sass compiler, [Autoprefixer](https://github.com/postcss/autoprefixer), [postcss-flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes), and [some setup]({{ site.baseurl }}/getting-started/build-tools/#tooling-setup). Download source -### Bootstrap CDN +## Bootstrap CDN Skip the download and use the Bootstrap CDN to deliver Bootstrap's compiled CSS and JS to your project. diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 3b9552278..43429db07 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -8,10 +8,11 @@ redirect_from: "/getting-started/" Bootstrap is the world's most popular framework for building responsive, mobile-first sites and applications. Inside you'll find high quality HTML, CSS, and JavaScript to make starting any project easier than ever. -Here's how to quickly get started with the Bootstrap CDN and a template starter page. - {% include ads.html %} + + + ## Contents * Will be replaced with the ToC, excluding the "Contents" header -- cgit v1.2.3 From 7ea1417b905a5e6da63aa1db8bc21dce31452133 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Fri, 6 Jan 2017 08:39:00 -0800 Subject: rubygems version bump --- docs/getting-started/download.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/download.md b/docs/getting-started/download.md index e953889f8..80f762a8d 100644 --- a/docs/getting-started/download.md +++ b/docs/getting-started/download.md @@ -56,13 +56,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.alpha5' +gem 'bootstrap', '~> 4.0.0.alpha6' {% endhighlight %} Alternatively, if you're not using Bundler, you can install the gem by running this command: {% highlight bash %} -gem install bootstrap -v 4.0.0.alpha5 +gem install bootstrap -v 4.0.0.alpha6 {% endhighlight %} [See the gem's README](https://github.com/twbs/bootstrap-rubygem/blob/master/README.md) for further details. -- cgit v1.2.3 From ec697b2076182836c58e2b3caa385d7e6b164d15 Mon Sep 17 00:00:00 2001 From: Pierre-Denis Vanduynslager Date: Sat, 14 Jan 2017 20:11:57 -0500 Subject: Update broken links. (#21696) --- docs/getting-started/build-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/build-tools.md b/docs/getting-started/build-tools.md index 0d441d216..04b2873b6 100644 --- a/docs/getting-started/build-tools.md +++ b/docs/getting-started/build-tools.md @@ -43,7 +43,7 @@ Our Gruntfile includes the following commands and tasks: Bootstrap uses [Autoprefixer][autoprefixer] (included in our Gruntfile and build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3. -We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/grunt/postcss.js`](https://github.com/twbs/bootstrap/blob/master/grunt/postcss.js) for details. +We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/grunt/postcss.js`](https://github.com/twbs/bootstrap/blob/v4-dev/grunt/postcss.js) for details. ## Local documentation -- cgit v1.2.3 From 57fe8ac84cda0f6e361b0d6a29e86c3adf87f83d Mon Sep 17 00:00:00 2001 From: Marios Zindilis Date: Sun, 15 Jan 2017 17:14:25 +0000 Subject: Fixed minor typo --- docs/getting-started/accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/accessibility.md b/docs/getting-started/accessibility.md index c1fe73dc0..33619eb1e 100644 --- a/docs/getting-started/accessibility.md +++ b/docs/getting-started/accessibility.md @@ -48,7 +48,7 @@ Note that this bug will also affect any other in-page links your site may be usi When nesting headings (`

` - `

`), your primary document header should be an `

`. Subsequent headings should make logical use of `

` - `

` such that screen readers can construct a table of contents for your pages. -Learn more at [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/Standards/Section508/) and [Penn State's Accessability](http://accessibility.psu.edu/headings/). +Learn more at [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/Standards/Section508/) and [Penn State's Accessibility](http://accessibility.psu.edu/headings/). ## Additional resources -- cgit v1.2.3 From 4fa7749442ea7ab609d1c8c25dc4ba750194e542 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sat, 21 Jan 2017 14:14:25 -0800 Subject: Drop Normalize, port relevant parts to Reboot (#21741) * Get this party started by removing mention of Normalize.css * Nuke the old comment, consolidate to a single line and number as appropriate * Bring over styles for HTML element from Normalize to Reboot * Move margin override for body element from Normalize to Reboot * Drop the block reset for HTML5 elements in IE9- from Normalize given we dropped IE9 support * Building on previous commit, do the same thing for figure, figcaption, and main * Remove IE9- display from Normalize given our browser support * Drop IE8 figure margin because we're IE10+ * No need for the h1 overrides because we reset these font and margin styles anyway in _type.scss already * Drop Safari 6 b and strong normalization because we're Safari 8+ * Remove mark styles for IE9- from Normalize * Remove old iOS audio fixes from Normalize * Remove IE9- display for progress from Normalize * Remove more IE9- rules from Normalize * One more IE9- display removal for canvas element * Move pre overrides from Normalize to Reboot * Move over some link resets to Reboot, drop others - Move over background-color and text-decoration - Drop focus outline change given it affects the offset on hover of focused links * Move over more code element resets, consolidate with pre overrides, too * Move over sub and sup wholesale * Move over img normalization to Reboot * Move over SVG override too * - Drop dupe hidden, but add comment for it - Move over template - Move over summary * Remove bulk of @viewport comment * edit down that code comment * consolidate html-based normalizations * update comments * Consolidate abbr styles * move over more type elements * move over hr changes * move over form controls and more * move over button resets * move over firefox button changes * move over search changes and more * we nuke all these styles for fieldsets anyway, so outright remove them * no need for those, we override them * move over legend, fieldset, progress * line break * delete normalize file * linting * update comment * clarify docs mentions of normalize and reboot * remove normalize excludes from linter * remove normalize excludes from cli task * linting * callout license since we forked part of normalize * Improve comments, move table background reset to .table class instead of in reboot * trailing space --- docs/getting-started/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 9d6fa2ce4..d70a42627 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -106,9 +106,9 @@ With the above snippet, nested elements—including generated content via `:befo Learn more about [box model and sizing at CSS Tricks](https://css-tricks.com/box-sizing/). -### Normalize.css +### Reboot -For improved cross-browser rendering, we use [Normalize.css](https://necolas.github.io/normalize.css/) to correct small inconsistencies across browsers and devices. We further build on this with our own, slightly more opinionated styles with [Reboot]({{ site.baseurl }}/content/reboot/). +For improved cross-browser rendering, we use [Reboot]({{ site.baseurl }}/content/reboot/) to correct inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements. ## Community -- cgit v1.2.3 From e8015e3f16e87c5ebaf6b10d9f627a1dc7f8fe65 Mon Sep 17 00:00:00 2001 From: Bardi Harborow Date: Mon, 27 Feb 2017 21:42:26 +1100 Subject: Fix broken links. --- docs/getting-started/download.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/download.md b/docs/getting-started/download.md index 80f762a8d..2323d3e4d 100644 --- a/docs/getting-started/download.md +++ b/docs/getting-started/download.md @@ -38,7 +38,7 @@ Pull in Bootstrap's **source files** into nearly any project with some of the mo ### npm -Install Bootstrap in your Node powered apps with [the npm package](https://www.npmjs.org/package/bootstrap): +Install Bootstrap in your Node powered apps with [the npm package](https://www.npmjs.com/package/bootstrap): {% highlight bash %} npm install bootstrap@{{ site.current_version }} -- cgit v1.2.3 From ed1de86794cc0911dc7a3dbbf3bb9dfe421ef4b6 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sun, 5 Mar 2017 12:20:44 -0800 Subject: Update spacer utilities (#22123) * Drop -x and -y as they're all the same - Also move -width to elsewhere in the vars because it makes no sense by spacers. - Update values of -x and -y across main Sass and docs Sass. * Update docs to reflect changes; link to spacing utils from options page --- docs/getting-started/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/options.md b/docs/getting-started/options.md index a1491252e..9638cd4ae 100644 --- a/docs/getting-started/options.md +++ b/docs/getting-started/options.md @@ -31,7 +31,7 @@ You can find and customize these variables for key global options in our `_varia | Variable | Values | Description | | --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- | -| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value for our spacer utilities. | +| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities](/utilities/spacing/). | | `$enable-rounded` | `true` (default) or `false` | Enables predefined `border-radius` styles on various components. | | `$enable-shadows` | `true` or `false` (default) | Enables predefined `box-shadow` styles on various components. | | `$enable-gradients` | `true` or `false` (default) | Enables predefined gradients via `background-image` styles on various components. | -- cgit v1.2.3 From 48c5efa4c3c439d8720b8475ec3e372c6974a12a Mon Sep 17 00:00:00 2001 From: Pierre Vanduynslager Date: Tue, 28 Mar 2017 17:43:16 -0400 Subject: Fix JS components console error "Error: is transitioning" --- docs/getting-started/javascript.md | 55 ++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 17 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/javascript.md b/docs/getting-started/javascript.md index b6a38fb7a..d65fba098 100644 --- a/docs/getting-started/javascript.md +++ b/docs/getting-started/javascript.md @@ -36,6 +36,18 @@ Alternatively, to target a specific plugin, just include the plugin's name as a $(document).off('.alert.data-api') {% endhighlight %} +## Events + +Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action. + +All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts. + +{% highlight js %} +$('#myModal').on('show.bs.modal', function (e) { + if (!data) return e.preventDefault() // stops modal from being shown +}) +{% endhighlight %} + ## Programmatic API We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon. @@ -54,32 +66,41 @@ $('#myModal').modal('show') // initializes and invokes show immed Each plugin also exposes its raw constructor on a `Constructor` property: `$.fn.popover.Constructor`. If you'd like to get a particular plugin instance, retrieve it directly from an element: `$('[rel="popover"]').data('popover')`. -### Default settings -You can change the default settings for a plugin by modifying the plugin's `Constructor.DEFAULTS` object: +### Asynchronous functions and transitions + +All programmatic API methods are **asynchronous** and returns to the caller once the transition is started but **before it ends**. +In order to execute an action once the transition is complete, you can listen to the corresponding event. {% highlight js %} -$.fn.modal.Constructor.DEFAULTS.keyboard = false // changes default for the modal plugin's `keyboard` option to false +$('#myCollapse').on('shown.bs.collapse', function (e) { + // Action to execute once the collapsible area is expanded +}) {% endhighlight %} -## No conflict +In addition a method call on a **transitioning component will be ignored**. +{% highlight js %} +$('#myCarousel').on('slid.bs.carousel', function (e) { + $('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished +}) -Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call `.noConflict` on the plugin you wish to revert the value of. +$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller +$('#myCarousel').carousel('2') // !! Will be ignored, as the transition to the slide 1 is not finished !! +{% endhighlight %} + +### Default settings +You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object: {% highlight js %} -var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value -$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality +$.fn.modal.Constructor.Default.keyboard = false // changes default for the modal plugin's `keyboard` option to false {% endhighlight %} -## Events - -Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action. +## No conflict -All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts. +Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call `.noConflict` on the plugin you wish to revert the value of. {% highlight js %} -$('#myModal').on('show.bs.modal', function (e) { - if (!data) return e.preventDefault() // stops modal from being shown -}) +var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value +$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality {% endhighlight %} ## Version numbers @@ -100,8 +121,8 @@ Bootstrap's plugins don't fall back particularly gracefully when JavaScript is d **Bootstrap does not officially support third-party JavaScript libraries** like Prototype or jQuery UI. Despite `.noConflict` and namespaced events, there may be compatibility problems that you need to fix on your own. {% endcallout %} -## Transitions +## Util -For simple transition effects, include `transition.js` once 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 Javascript 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. -Transition.js is 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. +`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. -- cgit v1.2.3 From 7ffb61ac5216493bd35a3ff9283f75d58c9ad94f Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Mon, 17 Apr 2017 00:04:49 +0100 Subject: Rewrite getting started/accessibility docs A long overdue rewrite of the accessibility section - instead of the few snippets of strangely superficial and out-of-context advice (skip links, use correct heading levels), this tries to answer some of the fundamental questions about "is Bootstrap accessible", with emphasis on the fact that the final result will depend in large part on what BS is applied to/on (since BS relies on the markup etc authored by developers). This also sets out our ambition to have things work for keyboard and assistive tech users, and that we strive to make all our examples etc accessible and semantic. * Changes based on @mdo's feedback --- docs/getting-started/accessibility.md | 52 +++++++++++++++++------------------ 1 file changed, 26 insertions(+), 26 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/accessibility.md b/docs/getting-started/accessibility.md index 33619eb1e..9a90c295c 100644 --- a/docs/getting-started/accessibility.md +++ b/docs/getting-started/accessibility.md @@ -1,57 +1,57 @@ --- layout: docs title: Accessibility -description: Learn how Bootstrap supports common web standards for making sites that are accessibile to those using assistive technology. +description: A brief overview of Bootstrap's features and limitations for the creation of accessible content. group: getting-started --- -Bootstrap follows common web standards and—with minimal extra effort—can be used to create sites that are accessible to those using AT. +Bootstrap provides an easy-to-use framework of ready-made styles, layout tools, and interactive components, allowing developers to create web sites and applications that are visually appealing, functionally rich, and accessible out of the box. ## Contents * Will be replaced with the ToC, excluding the "Contents" header {:toc} -## Component requirements +## Overview and limitations -Some common HTML elements are always in need for basic accessibility enhancements through `role`s and Aria attributes. Below is a list of some of the most frequently used ones. +The overall accessibility of any project built with Bootstrap depends in large part on the author's markup, additional styling, and scripting they've included. However, provided that these have been implemented correctly, it should be perfectly possible to create web sites and applications with Bootstrap that fulfill [WCAG 2.0](https://www.w3.org/TR/WCAG20/) (A/AA/AAA), [Section 508](https://www.section508.gov/) and similar accessibility standards and requirements. -### Button groups +### Structural markup -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"`. +Bootstrap's styling and layout can be applied to a wide range of markup structures. This documentation aims to provide developers with best practice examples to demonstrate the use of Bootstrap itself and illustrate appropriate semantic markup, including ways in which potential accessibility concerns can be addressed. -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. +### Interactive components -## Skip navigation +Bootstrap's interactive components—such as modal dialogs, dropdown menus and custom tooltips—are designed to work for touch, mouse and keyboard users. Through the use of relevant [WAI ARIA](https://www.w3.org/WAI/intro/aria) roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers). -If your navigation contains many links and comes before the main content in the DOM, add a `Skip to main content` link before the navigation (for a simple explanation, see this [A11Y Project article on skip navigation links](http://a11yproject.com/posts/skip-nav-links/)). Using the `.sr-only` class will visually hide the skip link, and the .sr-only-focusable class will ensure that the link becomes visible once focused (for sighted keyboard users). +Because Bootstrap's components are purposely designed to be fairly generic, authors may need to include further ARIA roles and attributes, as well as JavaScript behavior, to more accurately convey the precise nature and functionality of their component. This is usually noted in the documentation. -{% callout danger %} -Due to long-standing shortcomings/bugs in Internet Explorer (see this article on [in-page links and focus order](http://accessibleculture.org/articles/2010/05/in-page-links/)), you will need to make sure that the target of your skip link is at least programmatically focusable by adding `tabindex="-1"`. +### Color contrast -In addition, you may want to explicitly suppress a visible focus indication on the target (particularly as Chrome currently also sets focus on elements with `tabindex="-1"` when they are clicked with the mouse) with `#content:focus { outline: none; }`. +Most colors that currently make up Bootstrap's default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—lead to *insufficient* color contrast (below the recommended [WCAG 2.0 color contrast ratio of 4.5:1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html)) when used against a light background. Authors will need to manually modify/extend these default colors to ensure adequate color contrast ratios. -Note that this bug will also affect any other in-page links your site may be using, rendering them useless for keyboard users. You may consider adding a similar stop-gap fix to all other named anchors / fragment identifiers that act as link targets. -{% endcallout %} +### Visually hidden content + +Content which should be visually hidden, but remain accessible to assistive technologies such as screen readers, can be styled using the `.sr-only` class. This can be useful in situations where additional visual information or cues (such as meaning denoted through the use of color) need to also be conveyed to non-visual users. {% highlight html %} - - Skip to main content - ... -
- -
- +

+ Danger: + This action is not reversible +

{% endhighlight %} -## Nested headings - -When nesting headings (`

` - `

`), your primary document header should be an `

`. Subsequent headings should make logical use of `

` - `

` such that screen readers can construct a table of contents for your pages. +For visually hidden interactive controls, such as traditional "skip" links, `.sr-only` can be combined with the `.sr-only-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users). -Learn more at [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/Standards/Section508/) and [Penn State's Accessibility](http://accessibility.psu.edu/headings/). +{% highlight html %} +Skip to main content +{% endhighlight %} ## Additional resources -- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer) +- [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG20/) - [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/) +- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer) -- cgit v1.2.3 From 2906b612d5bc3d7e33950044c9b89a91b117df03 Mon Sep 17 00:00:00 2001 From: Bardi Harborow Date: Thu, 20 Apr 2017 20:33:51 +1000 Subject: More minor build tweaks and docs updates. --- docs/getting-started/build-tools.md | 29 +++++++++++++---------------- docs/getting-started/options.md | 2 +- 2 files changed, 14 insertions(+), 17 deletions(-) (limited to 'docs/getting-started') diff --git a/docs/getting-started/build-tools.md b/docs/getting-started/build-tools.md index 04b2873b6..8c5b635b3 100644 --- a/docs/getting-started/build-tools.md +++ b/docs/getting-started/build-tools.md @@ -5,7 +5,7 @@ description: Details on how to use Bootstrap's included build tools to compile s group: getting-started --- -Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build system and Jekyll for the written documentation. Our Gruntfile includes convenient methods for working with the framework, including compiling code, running tests, and more. +Bootstrap uses [NPM scripts](https://docs.npmjs.com/misc/scripts) for its build system. Our [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) includes convenient methods for working with the framework, including compiling code, running tests, and more. ## Contents @@ -14,49 +14,46 @@ Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build syst ## Tooling setup -To use our Gruntfile and run our documentation locally, you'll need a copy of Bootstrap's source files, Node, and Grunt. Follow these steps and you should be ready to rock: +To use our build system and run our documentation locally, you'll need a copy of Bootstrap's source files and Node. Follow these steps and you should be ready to rock: 1. [Download and install Node](https://nodejs.org/download/), which we use to manage our dependencies. -2. Install the Grunt command line tools, `grunt-cli`, with `npm install -g grunt-cli`. -3. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json). +2. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json). 4. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle install`. This will install all Ruby dependencies, such as Jekyll and plugins. - **Windows users:** Read [this unofficial guide](http://jekyll-windows.juthilo.com/) to get Jekyll up and running without problems. -When completed, you'll be able to run the various Grunt commands provided from the command line. +When completed, you'll be able to run the various commands provided from the command line. [install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ [gembundler]: https://bundler.io/ -## Using Grunt +## Using NPM scripts -Our Gruntfile includes the following commands and tasks: +Our [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) includes the following commands and tasks: | Task | Description | | --- | --- | -| `grunt` | Run `grunt` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** | -| `grunt dist` | `grunt dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** | -| `grunt test` | Runs [scss-lint](https://github.com/brigade/scss-lint), [ESLint](http://eslint.org/) and [QUnit](https://qunitjs.com/) tests headlessly in [PhantomJS](http://phantomjs.org/) (used for CI). | -| `grunt docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `jekyll serve`. | -| `grunt watch` | This is a convenience method for watching just Sass files and automatically building them whenever you save. | +| `npm test` | Run `npm test` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** | +| `npm run dist` | `npm run dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/), [Autoprefixer][autoprefixer], and [UglifyJS](http://lisperator.net/uglifyjs/).** | +| `npm run docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `npm run docs-serve`. | ## Autoprefixer -Bootstrap uses [Autoprefixer][autoprefixer] (included in our Gruntfile and build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3. +Bootstrap uses [Autoprefixer][autoprefixer] (included in our build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3. -We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/grunt/postcss.js`](https://github.com/twbs/bootstrap/blob/v4-dev/grunt/postcss.js) for details. +We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/build/postcss.js`](https://github.com/twbs/bootstrap/blob/v4-dev/build/postcss.js) for details. ## Local documentation Running our documentation locally requires the use of Jekyll, a decently flexible static site generator that provides us: basic includes, Markdown-based files, templates, and more. Here's how to get it started: 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 `bundle exec jekyll serve` in the command line. +2. From the root `/bootstrap` directory, run `npm run docs-serve` in the command line. 3. Open in your browser, and voilà. Learn more about using Jekyll by reading its [documentation](https://jekyllrb.com/docs/home/). ## Troubleshooting -Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`. +Should you encounter problems with installing dependencies, uninstall all previous dependency versions (global and local). Then, rerun `npm install`. [autoprefixer]: https://github.com/postcss/autoprefixer diff --git a/docs/getting-started/options.md b/docs/getting-started/options.md index 9638cd4ae..82d172f3e 100644 --- a/docs/getting-started/options.md +++ b/docs/getting-started/options.md @@ -5,7 +5,7 @@ description: Customize Bootstrap with Sass variables, easily toggling global pre group: getting-started --- -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 the included Gruntfile as needed. +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. ## Customizing variables -- cgit v1.2.3 From f7f644a4e52a7e875d5c8574d2a8b7fd919e5005 Mon Sep 17 00:00:00 2001 From: "Patrick H. Lauke" Date: Thu, 27 Apr 2017 23:57:10 +0100 Subject: Documentation cleanup (inc. use of for static form controls example) * Fix incorrect code indentation * Remove unnecessary vendor prefix for `box-sizing` - all modern browsers now support this unprefixed * Remove incorrect `