Merge branch 'v4-dev' of https://github.com/twbs/bootstrap into v4-dev

docs/_data/nav.yml

@@ -8,6 +8,7 @@
     - title: Options
     - title: Build tools
     - title: Best practices
+    - title: Webpack
     - title: Accessibility
 
 - title: Layout

docs/getting-started/build-tools.md

@@ -40,7 +40,7 @@ Our [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) i
 
 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 [`/build/postcss.js`](https://github.com/twbs/bootstrap/blob/v4-dev/build/postcss.js) for details.
+We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [`/build/postcss.config.js`](https://github.com/twbs/bootstrap/blob/v4-dev/build/postcss.config.js) for details.
 
 ## Local documentation
 

docs/getting-started/webpack.md

@@ -0,0 +1,106 @@
+---
+layout: docs
+title: Webpack
+description: Learn how to install Bootstrap using webpack 2
+group: getting-started
+---
+
+Use [webpack v2.x](https://webpack.js.org/) to bundle Bootstrap into your project.
+
+
+## Contents
+
+* Will be replaced with the ToC, excluding the "Contents" header
+{:toc}
+
+## Installing Bootstrap
+
+[Install bootstrap](/getting-started/download/#npm) as a node module using npm.
+
+## Importing JavaScript
+
+Import [Bootstrap's JavaScript](/getting-started/javascript/) by adding this line to your app's entry point (usally `index.js` or `app.js`):
+
+{% highlight js %}
+import 'bootstrap';
+{% endhighlight %}
+
+Alternatively, you may **import plugins individually** as needed:
+
+{% highlight js %}
+import 'bootstrap/js/dist/util';
+import 'bootstrap/js/dist/dropdown';
+...
+{% endhighlight %}
+
+Bootstrap is dependent on [jQuery](https://jquery.com/) and [Popper](https://popper.js.org/), so npm will install them for you if needed. But they must be explicitly provided by webpack. Add the following code to the `plugins` section in your webpack config file:
+
+{% highlight js %}
+  plugins: [
+    ...
+      new webpack.ProvidePlugin({
+        $: 'jquery',
+        jQuery: 'jquery',
+        'window.jQuery': 'jquery',
+        Popper: ['popper.js', 'default'],
+        // In case you imported plugins individually, you must also require them here:
+        Util: "exports-loader?Util!bootstrap/js/dist/util",
+        Dropdown: "exports-loader?Dropdown!bootstrap/js/dist/dropdown",
+        ...
+      })
+    ...
+  ]
+{% endhighlight %}
+
+{% callout warning %}
+Notice that if you chose to **import plugins individually**, you must also install [exports-loader](https://github.com/webpack-contrib/exports-loader)
+{% endcallout %}
+
+## Importing Styles
+
+### Importing Precompiled SASS
+
+To enjoy the full potential of Bootstrap and customize it to your needs, use the source files as a part of your project's bundling process. 
+
+First, create your own `_custom.scss` and use it to override the [built-in custom variables](/getting-started/options/). Then, use your main sass file to import your custom variables, followed by Bootstrap: 
+{% highlight scss %}
+@import "custom";
+@import "~bootstrap/scss/bootstrap";
+{% endhighlight %}
+
+For Bootstrap to compile, make sure you install and use the required loaders: [sass-loader](https://github.com/webpack-contrib/sass-loader), [postcss-loader](https://github.com/postcss/postcss-loader) with [Autoprefixer](https://github.com/postcss/autoprefixer#webpack) and [postcss-flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes). With minimal setup, your webpack config should include this rule or similar:
+
+{% highlight js %}
+  ...
+  {
+    test: /\.(scss)$/,
+    use: [{
+      loader: 'style-loader', // inject CSS to page
+    }, {
+      loader: 'css-loader', // translates CSS into CommonJS modules
+    }, {
+      loader: 'postcss-loader', // Run post css actions
+      options: {
+        plugins: function () { // post css plugins, can be exported to postcss.config.js
+          return [
+            require('precss'),
+            require('autoprefixer')
+          ];
+        }
+      }
+    }, {
+      loader: 'sass-loader' // compiles SASS to CSS
+    }]
+  },
+  ...
+{% endhighlight %}
+
+### Importing Compiled CSS
+
+Alternatively, you may use Bootstrap's ready-to-use css by simply adding this line to your project's entry point:
+
+{% highlight js %}
+import 'bootstrap/dist/css/bootstrap.min.css';
+{% endhighlight %}
+
+In this case you may use your existing rule for `css` without any special modifications to webpack config.