feat(doc): provide basic example for scss with webpack (#1150)

seanforyou23 · jeff-phillips-18 · commit b4d366196590 · 2018-10-17T16:08:17.000-04:00
improve readme to include example of webpack config
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ If you wish to contribute to PatternFly, please follow the instructions under "C
 
 PatternFly can be installed and managed through [NPM](https://www.npmjs.com/). To do so, either add `patternfly` as a dependency in your `package.json` or run the following:
 
-```
+```sh
 npm install patternfly --save
 ```
 
@@ -30,15 +30,15 @@ PatternFly stays up to date with the Node LTS [Release Schedule](https://github.
 
 PatternFly can be installed and managed through [Bower](http://bower.io/). To do so, either add `patternfly` as a dependency in your `bower.json` or run the following:
 
-```
+```sh
 bower install patternfly --save
 ```
 
 #### Using Wiredep?
 
 Are you using [Wiredep](https://github.com/taptapship/wiredep)?  PatternFly's CSS includes the CSS of its dependencies.  As a result, you'll want to add the following to your [Wiredep configuration](https://github.com/taptapship/wiredep#configuration) so you don't end up with duplicate CSS.
 
-```
+```javascript
 exclude: [
   "node_modules/patternfly/node_modules/patternfly-bootstrap-combobox/css/bootstrap-combobox.css",
   "node_modules/patternfly/node_modules/bootstrap-datepicker/dist/css/bootstrap-datepicker.css",
@@ -61,6 +61,41 @@ exclude: [
 **Patternfly now supports Sass natively!**
 Sass is included in the `dist/sass` directory. Just add `node_modules` to your build tool's Sass include paths then `@import 'patternfly/dist/sass/patternfly';` in your Sass to get started!
 
+#### Using Webpack?
+There are two touch points for integrating patternfly sass: one in your webpack config, and another in your sass. Below is an example module rule for loading patternfly .scss files using webpack.
+
+```javascript
+module: {
+  rules: [
+    {
+      test: /\.scss$/,
+      use: [
+        {
+          loader: 'sass-loader',
+          options: {
+            includePaths: [
+              // teach webpack to resolve these references
+              path.resolve(__dirname, 'node_modules', 'patternfly', 'dist', 'sass'),
+              path.resolve(__dirname, 'node_modules', 'bootstrap-sass', 'assets', 'stylesheets'),
+              path.resolve(__dirname, 'node_modules', 'font-awesome-sass', 'assets', 'stylesheets')
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+With webpack configured, just set the asset-path related variables and you're off!
+
+```scss
+$img-path: '~patternfly/dist/img/';
+$font-path: '~patternfly/dist/fonts/';
+$icon-font-path: '~patternfly/dist/fonts/';
+@import '~patternfly/dist/sass/patternfly';
+```
+
 Please note that the [patternfly-sass](https://github.com/patternfly/patternfly-sass) is no longer supported and will not include any features or fixes introduced after Patternfly 3.23.2. However, the [patternfly-sass](https://rubygems.org/gems/patternfly-sass) Rubygem is maintained further and built from this repository.
 
 ### AngularJS
@@ -93,13 +128,13 @@ The development includes the use of a number of helpful tasks. In order to setup
 
 To do this clone, and change directories into PatternFly:
 
-```
+```sh
 cd [PathToYourRepository]
 ```
 
 then
 
-```
+```sh
 npm install
 ```
 
@@ -115,13 +150,13 @@ Additionally you may need to install the grunt command line utility.  To do this
 
 Test pages are optionally generated using [Jekyll](http://jekyllrb.com/). To use jekyll to build the test pages, ensure Ruby is installed and available then run:
 
-```
+```sh
 npm run jekyll
 ```
 
 or
 
-```
+```sh
 gem install bundle
 bundle install
 ```
@@ -135,7 +170,7 @@ Next, set the environment variable PF_PAGE_BUILDER=jekyll.  eg.:
 
 Anytime you pull a new version of PatternFly, make sure you also run
 
-```
+```sh
 npm update
 ```
 
@@ -145,13 +180,13 @@ so you get the latest version of the dependencies specified in package.json.
 
 A local development server can be quickly fired up by using the Gruntjs serve task:
 
-```
+```sh
 npm start
 ```
 
 or
 
-```
+```sh
 grunt serve                 # will build first by default
 grunt serve --skipRebuild   # flag would allow you to skip the rebuild to save some time
 ```
@@ -168,7 +203,7 @@ PatternFly uses the [semantic-release tool](https://github.com/semantic-release/
 
 We have configured the [commitizen tool](https://github.com/commitizen/cz-cli) to assist you in formatting your commit messages corrctly.  To use this tool run the following command instead of `git commit`:
 
-```
+```sh
 npm run commit
 ```
 
@@ -212,13 +247,13 @@ The tool will prompt you with several questions that it will use to correctly fo
 
 In development, styling is written and managed through multiple Less files. In order to generate a CSS file of all styling, run the build Gruntjs task:
 
-```
+```sh
 npm run build
 ```
 
 or
 
-```
+```sh
 grunt build
 ```
 
@@ -227,14 +262,14 @@ This task will compile and minify the Less files into CSS files located at `dist
 ### Less to Sass Conversion
 Any time style changes are introduced, the Sass code will need to be updated to reflect those changes. The conversion is accomplished as part of the build, but in order to test the CSS you will need to build it from Sass:
 
-```
+```sh
 npm start -- --sass
 ```
 *Note the extra ` -- ` between `npm start` and the `--sass` flag. This syntax passes the flag on to the underlying grunt process instead of the npm command itself.*
 
 or
 
-```
+```sh
 grunt build --sass
 ```
 
@@ -249,7 +284,7 @@ Sass and Less do not have perfect feature parity, which can sometimes throw a wr
 #### Non-parametric Mixins
 Sass does not support non-parametric mixins in the same way that Less does. Mixins must be explictly declared in Sass, whereas any class definition in Less can be used as a non-parametric mixin. Sass does not have a feature that perfectly parallels this behavior, so we have to use the closest thing which is the `@extend` statement. However, an edge case exists where `@extend` statements are not allowed within media queries in Sass. This creates a scenario where uncompilable Sass code can be generated from perfectly acceptable Less. For example:
 **Less:**
-```
+```less
   .applauncher-pf {
     .applauncher-pf-title {
         .sr-only();
@@ -262,7 +297,7 @@ Sass does not support non-parametric mixins in the same way that Less does. Mixi
 ```
 
 **Converts to Sass:**
-```
+```scss
   .applauncher-pf {
     .applauncher-pf-title {
       @extend .sr-only;
@@ -277,7 +312,7 @@ Sass does not support non-parametric mixins in the same way that Less does. Mixi
 This breaks for two reasons. We cannot use the `@extend` statement directly inside a media query, and even if we are able to work around that by making applauncher-pf into a mixin and using the `@include` directive, `.applauncher-pf .applauncher-pf-title` uses the `@extend` directive, which would still fall within the media query via the mixin invocation. To fix this, the Less would need to be adjusted like this:
 
 **Less**
-```
+```less
   // Explicitly define a non-parametric sr-only mixin.
   .sr-only() {
     // sr-only rules;
@@ -304,7 +339,7 @@ This breaks for two reasons. We cannot use the `@extend` statement directly insi
 ```
 
 **Converts to Sass:**
-```
+```scss
   @mixin sr-only() {
     // sr-only rules
   }
@@ -327,42 +362,42 @@ This breaks for two reasons. We cannot use the `@extend` statement directly insi
 #### Tilde-Escaped Strings
 Strings that are escaped using the tilde in Less get converted to the Sass `unquote()` function. This causes Sass compilation issues when using escaped strings inside native CSS functions like `calc()`. Here is what happens:
 Less:
-```
+```less
 height: calc(~"100vh - 20px");
 ```
 Converts to Sass:
-```
+```scss
 height: calc(unqoute("100vh - 20px")):
 ```
 Which compiles directly to CSS and does not work as expected:
-```
+```css
 height: calc(unqoute("100vh - 20px")):
 ```
 
 To fix this, move the tilde operator outside of the `calc()` statement:
 
 Less:
-```
+```less
 height: ~"calc(100vh - 20px)";
 ```
 Converts to Sass:
-```
+```scss
 height: unqoute("calc(100vh - 20px)");
 ```
 Compiles to CSS:
-```
+```css
 height: calc(100vh - 20px);
 ```
 
 #### Comma Separated CSS Rules
 Using complex, comma separated rules in things like box shadows or backgrounds will cause conversion problems if they are not properly escaped. These rules should be escaped, and mixins and variables should not be used inline. For example, this statement should not be used in Less:
-```
+```css
 box-shadow: inset 0 1px 1px fade(@color-pf-black, 7.5%), 0 0 6px lighten(@state-danger-text, 20%);
 ```
 
 Instead, mixins should be assigned to variables, and variables should be interpolated in an escaped string like this:
 
-```
+```scss
 @color1: fade(@color-pf-black, 7.5%);
 @color2: lighten(@state-danger-text, 20%);
 box-shadow: ~"inset 0 1px 1px @{color1}, 0 0 6px @{color2}";
@@ -386,13 +421,13 @@ The HTML pages in `dist/tests` are generated using Jekyll.  Do *not* edit these
 ### Unit Testing
 Unit tests are written for [Karma test server] (https://karma-runner.github.io/1.0/index.html) with [Jasmine](http://jasmine.github.io/)
 
-```
+```sh
 npm test
 ```
 
 or
 
-```
+```sh
 grunt karma
 ```
 ### Visual Regression Testing
