diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b1a5ef09..d8a66bbb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -208,49 +208,3 @@ check tools and provid feedback.
By contributing your code, you agree to license your contribution under the [MIT License](LICENSE).
By contributing to the documentation, you agree to license your contribution under the [Creative Commons Attribution 3.0 Unported License](docs/LICENSE).
-
-## Development setup
-The development and testing with the documentation has been connected so we not only can utilize Material Design examples,
-but all of the original Bootstrap documentation examples as well. The most productive environment so far is to have
-Bootstrap checked out in parallel to this project, running three different terminal commands simultaneously:
-
-1. Bootstrap documentation
-
- ```bash
- cd bootstrap
- bundle install
- npm install
-
- # update docs and serve
- grunt dist docs && jekyll serve
- ```
-
-1. Initial build and watch
-
-This performs an initial build and watches both the core and docs sources for changes.
-
- ```bash
- cd bootstrap-material-design
- bundle install
- npm install
-
- # this is all you need after initial setup
- grunt dist docs watch
- ```
-
-1. Documentation
-
-(assuming the above is done)
-
- ```bash
- jekyll serve
- ```
-
-## Releasing
-
-1. Make sure travis succeeds first
-1. Update the version in `package.json`, it's version is used in the documentation
-1. Build the distribution `grunt prep-release`
-1. Commit
-1. Tag for bower - a valid tag starts with a `v` such as `v4.0.0`
-1. Push documentation with `grunt publish`
diff --git a/Gruntfile.js b/Gruntfile.js
index 7f53a1bb..f6f4c007 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -666,7 +666,7 @@ module.exports = function (grunt) {
grunt.registerTask('dist-css', ['sass-compile', 'postcss:core', 'csscomb:dist', 'cssmin:core', 'cssmin:docs']);
// Full distribution task.
- grunt.registerTask('dist', ['clean:dist', 'dist-css', 'dist-js']);
+ grunt.registerTask('dist', ['clean:dist', 'dist-css', 'dist-js', 'docs']);
// Default task.
grunt.registerTask('default', ['clean:dist', 'test']);
diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml
index 744e4b25..436923d8 100644
--- a/docs/_data/nav.yml
+++ b/docs/_data/nav.yml
@@ -3,10 +3,10 @@
- title: Introduction
- title: Download
- title: Browsers & devices
- - title: Options
- - title: Flexbox
- - title: Build tools
+ - title: Customization
- title: Best practices
+ - title: Build tools
+ - title: Release process
- title: Material Design
pages:
diff --git a/docs/getting-started/browsers-devices.md b/docs/getting-started/browsers-devices.md
index 2cfaf730..aa1e1f3c 100644
--- a/docs/getting-started/browsers-devices.md
+++ b/docs/getting-started/browsers-devices.md
@@ -4,6 +4,13 @@ title: Browsers and devices
group: getting-started
---
+{% callout info %}
+**Bootstrap Reference Documentation**
+This is a part of the reference documentation from Bootstrap.
+It is included here to ensure this critical information about compatibility is conveyed.
+{% endcallout %}
+
+
Bootstrap supports a wide variety of modern browsers and devices, and some older ones. See which exact ones below, as well as detailed information on known quirks and bugs.
## Contents
diff --git a/docs/getting-started/build-tools.md b/docs/getting-started/build-tools.md
index 61ec3d4f..3a60f08f 100644
--- a/docs/getting-started/build-tools.md
+++ b/docs/getting-started/build-tools.md
@@ -52,7 +52,8 @@ Material Design for Bootstrap uses [Autoprefixer][autoprefixer] (included in our
## 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:
+Running our documentation locally requires the use of Jekyll, a 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-material-design` directory, run `bundle exec jekyll serve` in the command line.
@@ -60,6 +61,39 @@ Running our documentation locally requires the use of Jekyll, a decently flexibl
Learn more about using Jekyll by reading its [documentation](http://jekyllrb.com/docs/home/).
+## Local development setup
+
+The development and testing with the documentation has been connected so we not only can utilize Material Design examples,
+but all of the original Bootstrap documentation examples as well. The most productive environment so far is to have
+Bootstrap checked out in parallel to this project, running three (3) different terminal commands simultaneously:
+
+1. _Terminal 1_: Bootstrap documentation for reference
+
+ 1. Performs an initial dependency setup/build
+
+ `bundle install && npm install && bower install && grunt dist`
+
+ 1. Start serving the documentation on
+
+ `jekyll serve`
+
+1. _Terminal 2_: Initial build and watch
+
+ 1. Performs an initial dependency setup/build
+
+ `bundle install && npm install && bower install && grunt dist`
+
+ 1. Watch both the core and docs sources for changes
+
+ `grunt watch`
+
+1. _Terminal 3_: Start serving documentation on with `jekyll serve`
+
+Now go forth and develop, the `watch` task will keep tabs on source files and docs files, meanwhile the `jekyll serve` command
+will generate new documentation pages with the changes. Simply refresh your browser to see the changes.
+
+(TODO: someone please investigate adding autoreload to jekyll development cycle)
+
## Troubleshooting
Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.
diff --git a/docs/getting-started/customization.md b/docs/getting-started/customization.md
new file mode 100644
index 00000000..704a9beb
--- /dev/null
+++ b/docs/getting-started/customization.md
@@ -0,0 +1,44 @@
+---
+layout: docs
+title: Customization options
+group: getting-started
+---
+
+Material Design for Bootstrap 4 is designed to be customized via Sass variables. You may customize any Bootstrap or MDB variable.
+
+{% callout info %}
+The following assumes you have [setup your Build tools](../build-tools)
+{% endcallout %}
+
+{% callout warning %}
+If overriding a variable via Sass, ensure that your are `@import`ing the _underscored_ file `_core.scss` **not** the main file used for distributions. For more information see this [StackOverflow post](http://stackoverflow.com/a/25191403/2363935).
+{% endcallout %}
+
+Here are some ways to customize:
+
+## 1. (Recommended) Include the source in your application
+
+Installing via Bower, customizing MDB is a breeze.
+
+1. Add `bootstrap-material-design` as a dependeny to your `bower.json`
+1. `bower install`
+1. In your application's Sass, redefine any customized variable _before_ `@import`ing bootstrap material design from your bower dependency directory. For example:
+
+~~~~~~~~
+$brand-primary: #3f51b5; // bootstrap variable
+$mdb-label-color-focus: #303f9f; // mdb variable
+
+@import "../bower_components/bootstrap-material-design/scss/core"; // make sure to use _core.scss!
+~~~~~~~~
+
+
+## 2. Download the source and change/compile
+
+{% callout warning %}
+This method is not recommended because it may be difficult to use source control **and** keep up to date with new releases. Please consider the recommended method above.
+{% endcallout %}
+
+1. Download the source via bower or otherwise
+2. Change any of the variables
+3. Run `grunt dist`
+
diff --git a/docs/getting-started/flexbox.md b/docs/getting-started/flexbox.md
deleted file mode 100644
index f8ab4e8a..00000000
--- a/docs/getting-started/flexbox.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-layout: docs
-title: Flexbox
-group: getting-started
----
-
-Flexbox support has finally come to Bootstrap. Opt-in to the new CSS layout styles with the flick of a variable or the swap of a stylesheet.
-
-## Contents
-
-* Will be replaced with the ToC, excluding the "Contents" header
-{:toc}
-
-## What's included
-
-Flexbox support is available for a number of Bootstrap's components:
-
-- The entire grid system (mixins and predefined classes), which switch from `float`s to `display: flex;`.
-- Input groups, which move from `display: table;` to `display: flex;`.
-- The media component moves from `display: table;` and a number of hacky styles to a simple `display: flex;`.
-
-Vendor prefixes are provided in our compiled CSS with Autoprefixer via Grunt.
-
-## Why flexbox?
-
-In a nutshell, flexbox provides simpler and more flexible layout options in CSS. More specifically, it provides:
-
-- Easy vertical alignment of content within a parent element.
-- Easy reordering of content across devices and screen resolutions with the help of media queries.
-- Easy CSS-only equal height columns for your grid-based layouts.
-
-All these things are possible outside flexbox, but typically require extra hacks and workarounds to do right.
-
-## How it works
-
-If you're familiar with modifying variables in Sass—or any other CSS preprocessor—you'll be right at home to move into flexbox mode.
-
-1. Open the `_variables.scss` file and find the `$enable-flex` variable.
-2. Change it from `false` to `true`.
-3. Recompile, and done!
-
-Alternatively, if you don't need the source Sass files, you may swap the default Bootstrap compiled CSS with the compiled flexbox variation. [Head to the download page]({{ site.baseurl }}/getting-started/download) for more information.
-
-## Browser support
-
-Enabling flexbox means **reduced browser and device support:**
-
-- Internet Explorer 9 and below do not support flexbox.
-- Internet Explorer 10 has a few known quirks (see the "Known issues" tab in [Can I use...](http://caniuse.com/#feat=flexbox)), requires using a prefix, and only supports the syntax from the old 2012 version of the spec.
-
-Please be extra conscious of your user base when enabling flexbox in your project. Visit [Can I use...](http://caniuse.com/#feat=flexbox) for details on browser support of flexbox.
diff --git a/docs/getting-started/options.md b/docs/getting-started/options.md
deleted file mode 100644
index 014a3985..00000000
--- a/docs/getting-started/options.md
+++ /dev/null
@@ -1,101 +0,0 @@
----
-layout: docs
-title: Customization options
-group: getting-started
----
-
-With Bootstrap 4, we've added a handful of global options for easily customizing all the components in your project. These options are handled by Sass variables. Simply change a variable's value and recompile with the included Gruntfile.
-
-## Available variables
-
-You can find and customize these variables in our `_variables.scss` file.
-
-| Variable | Values | Description |
-| --------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
-| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value for our spacer utilities. |
-| `$enable-flex` | `true` or `false` (default) | Swaps `float` and `display: table` styles for `display: flex`. |
-| `$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` various components. |
-| `$enable-transitions` | `true` (default) or `false` | Enables predefined `transition`s on various components. |
-| `$enable-hover-media-query` | `true` or `false` (default) | ... |
-
-
-## Color palette
-
-Bootstrap's color palette includes a numerical range of shades for each base color, heavily inspired by [Google's color palette](https://www.google.com/design/spec/style/color.html#color-color-palette). Base colors, which utilize Sass color functions to generate each shade, are indicated at the top of each stacked palette.
-
-
-
-
100
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-
-
500
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-
-
500
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-
-
500
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-
-
500
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-
-
500
-
100
-
200
-
300
-
400
-
500
-
600
-
700
-
800
-
900
-
-