Merge branch 'master' into rebuild

Author: montogeek

.github/CONTRIBUTING.md

@@ -16,7 +16,7 @@ Start by ensuring you have Node installed and forking the repository:
 
 Once you are in the project directory, run the following commands:
 
-- `npm install` to pull all dependencies.
+- `npm install` to pull all dependencies. Make sure to check notes below if you prefer Yarn.
 - `npm run build` to create a production version of the site.
 - `npm start` to develop on a local webpack-dev-server: [localhost:3000][3].
 - `npm run fetch` to retrieve external documentation/data.
@@ -30,6 +30,8 @@ See the `package.json` for the full list of `scripts`.
 
 > Note that a __Python version between v2.5.0 and 3.0.0__ is required for the [proselint][12] dependency.
 
+> Although __Yarn__ is not required to work with webpack docs, the core team is using it more extensively. If you prefer to use Yarn make sure you [got it installed][13] and run `yarn` to pull all dependencies, `yarn build` to build the project, or `yarn start` to start development server.
+
 > On Debian and Ubuntu operating systems you may have to use `node >= 7.0.0` to avoid build errors with `node-sass`. Please note that we don't officially support building on these systems.
 
 
@@ -59,7 +61,7 @@ Making a branch in your fork for your contribution is helpful in the following w
 
 ## Committing Your Changes
 
-Please follow the [conventionalcommits][10] specification. For example, for documentation
+Please follow the [conventional commits][10] specification. For example, for documentation
 changes, a short commit message may resemble the following:
 
 ``` md
@@ -125,3 +127,4 @@ any time spent fixing typos or clarifying sections in the documentation.
 [10]: http://conventionalcommits.org/
 [11]: https://github.com/conventional-changelog/standard-version
 [12]: https://github.com/amperser/proselint
+[13]: https://yarnpkg.com/lang/en/docs/install

.github/ISSUE_TEMPLATE/Documentation_request.md

@@ -0,0 +1,16 @@
+---
+name: Documentation request
+about: Create a documentation request for a new feature or functionality change.
+---
+
+**Feature to document**
+
+<!-- Name of the feature(s) and a link to related pull request of the feature implementation. -->
+
+**Author(s)**
+
+<!-- Mention feature author(s) in order to know who is assignable for review outside of the documentation team. -->
+
+**Additional information**
+
+<!-- Please provide any additional information that is required in order to document the feature in the best possible way or say N/A if linked PR has more than enough details. -->

.gitignore

@@ -7,3 +7,4 @@ src/**/_*.md
 .DS_Store
 npm-debug.log
 yarn-error.log
+package-lock.json

.npmrc

@@ -0,0 +1 @@
+package-lock=false

.travis.yml

@@ -9,5 +9,7 @@ sudo: required
 install:
   - yarn
   - sudo pip install proselint
+before_script:
+  - source ./src/scripts/env.sh
 script:
   - bash ./src/scripts/deploy.sh

package.json

@@ -27,6 +27,7 @@
     "clean": "rimraf ./dist src/content/**/_*.md src/**/_*.json",
     "start": "NODE_ENV=development webpack-dev-server --config webpack.dev.js --env.dev",
     "content": "node src/scripts/build-content-tree.js ./src/content ./src/_content.json",
+    "build-test": "npm run build && http-server build/",
     "fetch": "sh src/scripts/fetch.sh",
     "prebuild": "npm run clean",
     "build": "npm run fetch && npm run content && NODE_ENV=production webpack --config webpack.prod.js && npm run sitemap && echo webpack.js.org > dist/CNAME",
@@ -40,6 +41,11 @@
     "serve": "npm run build && sirv start ./dist --port 4000",
     "deploy": "gh-pages -d dist"
   },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm test"
+    }
+  },
   "devDependencies": {
     "@octokit/rest": "^15.2.6",
     "alex": "^5.1.0",
@@ -67,6 +73,11 @@
     "gh-pages": "^1.0.0",
     "html-webpack-plugin": "^2.30.1",
     "html-webpack-template": "^6.1.0",
+    "github": "^10.0.0",
+    "http-server": "^0.10.0",
+    "husky": "^1.0.0-rc.8",
+    "hyperlink": "^3.0.1",
+    "loader-utils": "^1.1.0",
     "lodash": "^4.17.4",
     "markdownlint": "^0.6.0",
     "markdownlint-cli": "0.10.0",

src/components/Contributors/Contributors.jsx

@@ -14,7 +14,7 @@ export default ({contributors}) => {
             <a key={ contributor }
               className="contributor"
               href={ `https://github.com/${contributor}` }>
-              <img src={ `https://github.com/${contributor}.png?size=90` } />
+              <img alt={ contributor } src={ `https://github.com/${contributor}.png?size=90` } />
               <span className="contributor__name"> {contributor}</span>
             </a>
           ))

src/components/Dropdown/Dropdown.jsx

@@ -23,7 +23,7 @@ export default class Dropdown extends React.Component {
           src={ LanguageIcon } />
         {/* Commented out until media breakpoints are in place
         <span>{ items[0].title }</span> */}
-        <i className="dropdown__arrow" />
+        <i aria-hidden="true" className="dropdown__arrow" />
 
         <div className={ `dropdown__list ${activeMod}` }>
           <ul>

src/components/Markdown/Markdown.scss

@@ -118,13 +118,13 @@
     }
 
     &.tip {
-      background-color: #DCF2FD;
-      color: #618ca0;
+      background-color: #eaf8ff;
+      color: #4e7182;
     }
 
     &.warning {
-      background-color: #fbedb7;
-      color: #8c8466;
+      background-color: #fdf5d8;
+      color: #716b53;
     }
 
     &.todo {
@@ -279,7 +279,7 @@
     margin: 0 2px;
     padding: 2px 6px;
     white-space: normal;
-    background-color: transparentize(getColor(fiord), 0.94);
+    background-color: transparentize(getColor(fiord), 0.95);
     border-radius: 3px;
     text-shadow: 0 1px 0 transparentize(getColor(white), 0.4);
   }

src/components/Markdown/prism-theme.scss

@@ -41,7 +41,7 @@ pre[class*="lang-"] {
 .token.prolog,
 .token.doctype,
 .token.cdata {
-  color: #77858c;
+  color: #93a4ad;
 }
 
 .token.punctuation {
@@ -71,7 +71,7 @@ pre[class*="lang-"] {
 .token.regex,
 .token.attr-value,
 .token.important {
-  color: desaturate(#2dd271, 25%)
+  color: desaturate(#2dd271, 23%)
 }
 
 .token.inserted {

src/components/Navigation/Navigation.jsx

@@ -31,13 +31,13 @@ export default class Navigation extends React.Component {
             title: 'GitHub Repository',
             url: 'https://github.com/webpack/webpack',
             className: 'navigation__item--icon',
-            content: <i className="icon-github" />
+            content: <i aria-hidden="true" className="icon-github" />
           },
           {
             title: 'Webpack on Stack Overflow',
             url: 'https://stackoverflow.com/questions/tagged/webpack',
             className: 'navigation__item--icon',
-            content: <i className="icon-stack-overflow" />
+            content: <i aria-hidden="true" className="icon-stack-overflow" />
           },
           {
             className: 'navigation__item--icon',

src/components/NotificationBar/NotificationBar.jsx

@@ -24,7 +24,11 @@ class MessageBar extends React.Component {
             <a href="https://opencollective.com/webpack">open collective</a>!
           </p>
           {localStorageIsEnabled ? (
-            <button className="notification-bar__close icon-cross" onClick={this.close.bind(this)} />
+            <button
+              aria-label="Dismiss"
+              className="notification-bar__close icon-cross"
+              onClick={this.close.bind(this)}
+            />
           ) : null}
         </Container>
       </div>

src/components/Shield/Shield.jsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 export default props => (
-  <img src={
+  <img alt="webpack shield" src={
     `https://img.shields.io/${props.content}.svg?label=${props.label}&style=flat-square&maxAge=3600`
   } />
 );

src/components/SplashViz/SplashVizSVG.js

@@ -45,8 +45,8 @@ module.exports = {
         <g transform="translate(342, 225)" stroke="#7E8C94" stroke-width="4">
             <path d="M499.558824,86.52 C499.558824,86.52 484.852941,81.02 439.908088,109.436667 C394.963235,137.853333 380.992647,164.436667 380.992647,164.436667" stroke-dasharray="7"></path>
             <path d="M499.558824,86.0616667 C499.558824,86.0616667 484.852941,91.5616667 439.908088,63.145 C394.963235,34.7283333 380.992647,8.145 380.992647,8.145" stroke-dasharray="7"></path>
-            <path d="M0.477941176,170.395 C0.477941176,170.395 169.382939,98.895 447.847936,98.895" id="Shape_99_" stroke-dasharray="6"></path>
-            <path d="M0.477941176,72.395 C0.477941176,72.395 169.382939,0.895 447.847936,0.895" id="Shape_99_" stroke-dasharray="6" transform="translate(224.162939, 36.645000) scale(1, -1) translate(-224.162939, -36.645000) "></path>
+            <path d="M0.477941176,170.395 C0.477941176,170.395 169.382939,98.895 447.847936,98.895" stroke-dasharray="6"></path>
+            <path d="M0.477941176,72.395 C0.477941176,72.395 169.382939,0.895 447.847936,0.895" stroke-dasharray="6" transform="translate(224.162939, 36.645000) scale(1, -1) translate(-224.162939, -36.645000) "></path>
         </g>
         <text font-family="'Source Sans Pro', sans-serif" font-size="18" font-weight="600" fill="#86A5BA">
             <tspan x="24.934" y="562">MODULES WITH DEPENDENCIES</tspan>

src/content/api/cli.md

@@ -98,6 +98,8 @@ This will form the bundle with both the files as separate entry points.
 
 ### Common Options
 
+W> Note that Command Line Interface has a higher precendence for the arguments you use it with than your configuration file. For instance, if you pass [`--mode="production"`](/concepts/mode/#usage) to webpack CLI and your configuration file uses `development`, `production` will be used.
+
 **List all of the options available on the cli**
 
 ```bash
@@ -170,6 +172,7 @@ Parameter                 | Explanation                                 | Input
 `--output-pathinfo`       | Include a comment with the request for every dependency | boolean | false
 `--output-public-path`    | The public path for the assets              | string     | /
 `--output-source-map-filename` | The output filename for the SourceMap  | string     | [name].map or [outputFilename].map
+`--build-delimiter` | Display custom text after build output | string | Default string is null. You could provide a string such as `=== Build done ===`
 
 
 #### Example Usage

src/content/api/compiler-hooks.md

@@ -217,7 +217,7 @@ Parameters: `compilation`
 
 ### `done`
 
-`SyncHook`
+`AsyncSeriesHook`
 
 Compilation has completed.
 

src/content/concepts/index.md

@@ -19,10 +19,11 @@ At its core, **webpack** is a _static module bundler_ for modern JavaScript appl
 
 T> Learn more about JavaScript modules and webpack modules [here](/concepts/modules).
 
-Since version 4, **webpack does not require a configuration file** to bundle your project, nevertheless it is [incredibly configurable](/configuration) to better fit your needs.
+Since version 4.0.0, **webpack does not require a configuration file** to bundle your project, nevertheless it is [incredibly configurable](/configuration) to better fit your needs.
 
 To get started you only need to understand its **Core Concepts**:
 
+
 - Entry
 - Output
 - Loaders
@@ -79,7 +80,7 @@ Out of the box, webpack only understands JavaScript files. **Loaders** allow web
 
 W> Note that the ability to `import` any type of module, e.g. `.css` files, is a feature specific to webpack and may not be supported by other bundlers or task runners. We feel this extension of the language is warranted as it allows developers to build a more accurate dependency graph.
 
-At a high level, **loaders** have two purposes in your webpack configuration:
+At a high level, **loaders** have two properties in your webpack configuration:
 
 1. The `test` property identifies which file or files should be transformed.
 2. The `use` property indicates which loader should be used to do the transforming.

src/content/concepts/mode.md

@@ -10,6 +10,8 @@ Providing the `mode` configuration option tells webpack to use its built-in opti
 
 `string`
 
+T> The default value for `mode` is `production`.
+
 ## Usage
 
 Just provide the `mode` option in the config:
@@ -27,14 +29,16 @@ or pass it as a [CLI](/api/cli/) argument:
 webpack --mode=production
 ```
 
-If not set, webpack sets `production` as the default value for `mode`. The supported values for mode are:
+The following string values are supported:
 
 Option                | Description
 --------------------- | -----------------------
 `development`         | Provides `process.env.NODE_ENV` with value `development`. Enables `NamedChunksPlugin` and `NamedModulesPlugin`.
 `production`          | Provides `process.env.NODE_ENV` with value `production`. Enables `FlagDependencyUsagePlugin`, `FlagIncludedChunksPlugin`, `ModuleConcatenationPlugin`, `NoEmitOnErrorsPlugin`, `OccurrenceOrderPlugin`, `SideEffectsFlagPlugin` and `UglifyJsPlugin`.
 `none`                | Opts out of any default optimization options
 
+If not set, webpack sets `production` as the default value for `mode`. The supported values for mode are:
+
 T> Please remember that setting `NODE_ENV` doesn't automatically set `mode`.
 
 

src/content/concepts/output.md

@@ -68,7 +68,7 @@ module.exports = {
 };
 ```
 
-In cases when the eventual `publicPath` of output files isn't known at compile time, it can be left blank and set dynamically at runtime in the entry point file. If you don't know the `publicPath` while compiling, you can omit it and set `__webpack_public_path__` on your entry point.
+In cases where the eventual `publicPath` of output files isn't known at compile time, it can be left blank and set dynamically at runtime via the `__webpack_public_path__` variable in the entry point file:
 
 ```javascript
 __webpack_public_path__ = myRuntimePublicPath;

src/content/concepts/plugins.md

@@ -16,7 +16,7 @@ They also serve the purpose of doing **anything else** that a [loader](/concepts
 
 ## Anatomy
 
-A webpack **plugin** is a JavaScript object that has an [`apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply) property. This `apply` property is called by the webpack compiler, giving access to the **entire** compilation lifecycle.
+A webpack **plugin** is a JavaScript object that has an [`apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply) method. This `apply` method is called by the webpack compiler, giving access to the **entire** compilation lifecycle.
 
 __ConsoleLogOnBuildWebpackPlugin.js__
 

src/content/configuration/configuration-languages.md

@@ -67,7 +67,8 @@ __tsconfig-for-webpack-config.json__
 {
   "compilerOptions": {
     "module": "commonjs",
-    "target": "es5"
+    "target": "es5",
+    "esModuleInterop": true
   }
 }
 ```

src/content/configuration/devtool.md

@@ -35,8 +35,8 @@ eval                           | +++   | +++     | no         | generated code
 cheap-eval-source-map          | +     | ++      | no         | transformed code (lines only)
 cheap-module-eval-source-map   | o     | ++      | no         | original source (lines only)
 eval-source-map                | --    | +       | no         | original source
-cheap-source-map               | +     | o       | no         | transformed code (lines only)
-cheap-module-source-map        | o     | -       | no         | original source (lines only)
+cheap-source-map               | +     | o       | yes        | transformed code (lines only)
+cheap-module-source-map        | o     | -       | yes        | original source (lines only)
 inline-cheap-source-map        | +     | o       | no         | transformed code (lines only)
 inline-cheap-module-source-map | o     | -       | no         | original source (lines only)
 source-map                     | --    | --      | yes        | original source

src/content/configuration/index.md

@@ -61,6 +61,7 @@ module.exports = {
     b: ["./app/entry-b1", "./app/entry-b2"]
   },
   </details>
+  // defaults to ./src
   // Here the application starts executing
   // and webpack starts bundling
   [output](/configuration/output): {

src/content/configuration/module.md

@@ -8,6 +8,7 @@ contributors:
   - jhnns
   - dylanonelson
   - byzyk
+  - pnevares
 ---
 
 These options determine how the [different types of modules](/concepts/modules) within a project will be treated.
@@ -24,16 +25,17 @@ Prevent webpack from parsing any files matching the given regular expression(s).
 ```js
 module.exports = {
   //...
-  noParse: /jquery|lodash/,
+  module: {
+    noParse: /jquery|lodash/,
 
-  // since webpack 3.0.0
-  noParse: function(content) {
-    return /jquery|lodash/.test(content);
+    // since webpack 3.0.0
+    noParse: function(content) {
+      return /jquery|lodash/.test(content);
+    }
   }
 };
 ```
 
-
 ## `module.rules`
 
 `array`
@@ -96,7 +98,10 @@ Specifies the category of the loader. No value means normal loader.
 
 There is also an additional category "inlined loader" which are loaders applied inline of the import/require.
 
-All loaders are sorted in the order `pre, inline, normal, post` and used in this order.
+There are two phases that all loaders enter one after the other:
+
+1. __Pitching__ phase: the pitch method on loaders is called in the order `post, inline, normal, pre`. See [Pitching Loader](/api/loaders/#pitching-loader) for details.
+2. __Normal__ phase: the normal method on loaders is executed in the order `pre, normal, inline, post`. Transformation on the source code of a module happens in this phase.
 
 All normal loaders can be omitted (overridden) by prefixing `!` in the request.
 
@@ -246,6 +251,13 @@ module.exports = {
 An array of [`Rules`](#rule) that is also used when the Rule matches.
 
 
+## `Rule.sideEffects`
+
+Possible values: `false | an array of paths`
+
+Indicate what parts of the module contain side effects. See [Tree Shaking](/guides/tree-shaking/#mark-the-file-as-side-effect-free) for details.
+
+
 ## `Rule.test`
 
 `Rule.test` is a shortcut to `Rule.resource.test`. If you supply a `Rule.test` option, you cannot also supply a `Rule.resource`. See [`Rule.resource`](#rule-resource) and [`Condition.test`](#condition) for details.