documentation updates

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`

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']);

docs/_data/nav.yml

@@ -3,10 +3,10 @@
     - title: Introduction
     - title: Download
     - title: Browsers & devices
-    - title: Options
+    - title: Customization
-    - title: Flexbox
-    - title: Build tools
     - title: Best practices
+    - title: Build tools
+    - title: Release process
 
 - title: Material Design
   pages:

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 <a href="http://getbootstrap.com">Bootstrap</a>. 
+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

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 <http://localhost:9000>
+      
+        `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 <http://localhost:9001> 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`.

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`
+

docs/getting-started/flexbox.md

@@ -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.

docs/getting-started/options.md

@@ -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.
-
-<div class="row">
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base gray-100">100</div>
-    <div class="color-slab gray-100">100</div>
-    <div class="color-slab gray-200">200</div>
-    <div class="color-slab gray-300">300</div>
-    <div class="color-slab gray-400">400</div>
-    <div class="color-slab gray-500">500</div>
-    <div class="color-slab gray-600">600</div>
-    <div class="color-slab gray-700">700</div>
-    <div class="color-slab gray-800">800</div>
-    <div class="color-slab gray-900">900</div>
-  </div>
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base blue-500">500</div>
-    <div class="color-slab blue-100">100</div>
-    <div class="color-slab blue-200">200</div>
-    <div class="color-slab blue-300">300</div>
-    <div class="color-slab blue-400">400</div>
-    <div class="color-slab blue-500">500</div>
-    <div class="color-slab blue-600">600</div>
-    <div class="color-slab blue-700">700</div>
-    <div class="color-slab blue-800">800</div>
-    <div class="color-slab blue-900">900</div>
-  </div>
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base green-500">500</div>
-    <div class="color-slab green-100">100</div>
-    <div class="color-slab green-200">200</div>
-    <div class="color-slab green-300">300</div>
-    <div class="color-slab green-400">400</div>
-    <div class="color-slab green-500">500</div>
-    <div class="color-slab green-600">600</div>
-    <div class="color-slab green-700">700</div>
-    <div class="color-slab green-800">800</div>
-    <div class="color-slab green-900">900</div>
-  </div>
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base teal-500">500</div>
-    <div class="color-slab teal-100">100</div>
-    <div class="color-slab teal-200">200</div>
-    <div class="color-slab teal-300">300</div>
-    <div class="color-slab teal-400">400</div>
-    <div class="color-slab teal-500">500</div>
-    <div class="color-slab teal-600">600</div>
-    <div class="color-slab teal-700">700</div>
-    <div class="color-slab teal-800">800</div>
-    <div class="color-slab teal-900">900</div>
-  </div>
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base orange-500">500</div>
-    <div class="color-slab orange-100">100</div>
-    <div class="color-slab orange-200">200</div>
-    <div class="color-slab orange-300">300</div>
-    <div class="color-slab orange-400">400</div>
-    <div class="color-slab orange-500">500</div>
-    <div class="color-slab orange-600">600</div>
-    <div class="color-slab orange-700">700</div>
-    <div class="color-slab orange-800">800</div>
-    <div class="color-slab orange-900">900</div>
-  </div>
-  <div class="col-sm-6 col-md-4 color-palette">
-    <div class="color-slab color-slab-base red-500">500</div>
-    <div class="color-slab red-100">100</div>
-    <div class="color-slab red-200">200</div>
-    <div class="color-slab red-300">300</div>
-    <div class="color-slab red-400">400</div>
-    <div class="color-slab red-500">500</div>
-    <div class="color-slab red-600">600</div>
-    <div class="color-slab red-700">700</div>
-    <div class="color-slab red-800">800</div>
-    <div class="color-slab red-900">900</div>
-  </div>
-</div>

docs/getting-started/release-process.md

@@ -0,0 +1,50 @@
+---
+layout: docs
+title: Release process
+group: getting-started
+---
+
+Material Design for Bootstrap has a well defined release process that is automated by [Grunt](http://gruntjs.com).  See the [Build Tools](../build-tools) section for setup.
+
+## Creating a release
+
+### Add a release issue to Github
+
+Use the following task template:
+
+~~~~~~~~
+  - [] update `package.json` version
+  - [] `grunt prep-release`
+  - [] commit
+  - [] travis success
+  - [] tag for bower e.g. `v4.0.0`
+  - [] push to npm
+  - [] push to meteor
+  - [] `grunt publish`
+  - [] close any milestone
+  - [] create release and reference milestone issues</code>
+~~~~~~~~
+
+  
+### Build the release
+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. Ensure travis succeeds
+
+### Bower
+Tag for bower - a valid tag starts with a `v` such as `v4.0.0`
+
+### NPM
+TODO: push to npm?
+
+### Meteor
+TODO: push to meteor?
+
+### Github tasks
+1. Push documentation with `grunt publish`
+1. Close any related open milestone
+1. Create a release and reference the milestone
+
+
+