Merge pull request #18921 from twbs/v4-custom-docs

mdo · mdo · commit 94e27cdd6e51 · 2016-01-17T16:05:27.000-08:00
Update docs to include mention of the custom variables file
diff --git a/docs/getting-started/options.md b/docs/getting-started/options.md
@@ -4,11 +4,29 @@ 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.
+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.
 
-## Available variables
+## Customizing variables
 
-You can find and customize these variables in our `_variables.scss` file.
+Bootstrap 4 ships with a `_custom.scss` file for easy variable overrides. Copy and paste relevant lines from `_variables.scss` into the custom file and recompile your Sass to change our default values. **Be sure to remove the `!default` flag from override values.**
+
+For example, to change out the `background-color` and `color` for the `<body>`, you'd do the following:
+
+{% highlight scss %}
+// Bootstrap overrides
+//
+// Copy variables from `_variables.scss` to this file to override default values
+// without modifying source files.
+
+$body-bg:    $gray-dark;
+$body-color: $gray-light;
+{% endhighlight %}
+
+Do the same for any variable you need to override, including the global options listed below.
+
+## Global options
+
+You can find and customize these variables for key global options in our `_variables.scss` file.
 
 | Variable                    | Values                             | Description                                                             |
 | --------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
diff --git a/scss/_custom.scss b/scss/_custom.scss
@@ -1,4 +1,4 @@
-// Custom Overrides
+// Bootstrap overrides
 //
-// Copy settings from `_variables.scss` to this file to override
-// the Bootstrap defaults without modifying key, versioned files.
+// Copy variables from `_variables.scss` to this file to override default values
+// without modifying source files.
