docs: add description of bundle formats in the Javascript doc

diff --git a/docs/pages/javascript.md b/docs/pages/javascript.md
index 26e57aec2c5deb4e8f94b9bc3fc22f9b73a8f8c4..dc0af0a5b243eeaa6b8ed9ba186b1e74fce30260 100644 (file)
--- a/docs/pages/javascript.md
+++ b/docs/pages/javascript.md
@@ -39,7 +39,7 @@ Know that they all require `foundation.core.js` to be loaded *first*. Some plugi
 
 ### Import in JavaScript
 
-Foundation is exported as [UMD modules](http://bob.yexley.net/umd-javascript-that-runs-anywhere/). This means that Foundation and its plugins can be imported in any JavaScript environnement.
+By default, Foundation is exported as [UMD modules](http://bob.yexley.net/umd-javascript-that-runs-anywhere/). This means that Foundation and its plugins can be imported and used in any JavaScript environnement.
 
 For example with [ES6](https://github.com/lukehoban/es6features#readme) (the ESM format):
 ```js
@@ -63,6 +63,22 @@ var Foundation = require('foundation-sites');
 var $dropdown = new Dropdown('#mydropdown');
 ```
 
+#### All Javascript bundles
+
+Foundation is proposed in bundles of various module formats so you can pick the one that match the best your needs. If you don't know these terms yet, take a look at this [10-minute introduction to module formats in JavaScript](https://www.jvandemo.com/a-10-minute-primer-to-javascript-modules-module-formats-module-loaders-and-module-bundlers/). You will find in the `dist/js` folder the following bundles:
+
+* `foundation.js` <span class="label secondary">UMD</span> <span class="label">Default</span><br>
+  Compatible with most environments and tools (AMD, CJS, ESM...). It works almost everywhere by checking the module format of your environments and then using it, which make the bundle a little heavier.
+
+* `foundation.cjs.js` <span class="label secondary">CommonJS</span><br>
+  Dedicated to Node.js and older bundlers like Browserify or Webpack v1.
+
+* `foundation.esm.js` <span class="label secondary">ES6 Modules</span><br>
+  Everything is transpiled to ES5 but the modules. Dedicated to modern bundlers, like Webpack 2+ or Rollup. They will automatically use this bundle and parse the ES6 modules to remove the unused code (see [tree shaking](#tree-shaking) below).
+
+* `foundation.es6.js` <span class="label secondary">ES6</span><br>
+  Unlike the others bundles, this bundle is not transpiled. It contains all the Foundation sources in ES6 in a single file. Use it if you want to manually transpile it for your own targets.
+
 #### Tree Shaking
 
 Many bundlers like Webpack, Rollup or Parcel support tree shaking. It consists of the removing the unused code parts from your codebase or your dependencies. Take a look at these articles to know how it works and how to enable it: [How To Clean Up Your JavaScript Build With Tree Shaking](https://www.engineyard.com/blog/tree-shaking), [Why Webpack 2's Tree Shaking is not as effective as you think](https://advancedweb.hu/2017/02/07/treeshaking/) and [Reduce JavaScript Payloads with Tree Shaking](https://developers.google.com/web/fundamentals/performance/optimizing-javascript/tree-shaking/).