Revise building readme

BUILDING.md

@@ -1,6 +1,24 @@
-# Building plotly.js
+# Alternative ways to require or build plotly.js
+Depending on your needs, to bundle plotly.js into your application one of [the browserified distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) on npm could be used.
 
-The easiest way to bundle plotly.js into your application is to use one of the distributed plotly.js packages on npm. These distributed packages should just work with **any** build framework. That said, if you're looking to save a few bytes, read the section below corresponding to your building framework.
+## Browserify example
+
+Given source file:
+```js
+// file: index.js
+var Plotly = require('plotly.js-dist-min');
+// ....
+```
+
+then simply run
+
+```sh
+browserify index.js > bundle.js
+```
+
+
+
+The section below provide additional info in respect to alternative building frameworks.
 
 ## Webpack
 
@@ -21,24 +39,6 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here]
 ...
 ```
 
-## Browserify
-
-Given source file:
-
-```js
-// file: index.js
-
-var Plotly = require('plotly.js');
-
-// ....
-```
-
-then simply run,
-
-```
-browserify index.js > bundle.js
-```
-
 ## Angular CLI
 
 Since Angular uses webpack under the hood and doesn't allow easily to change it's webpack configuration, there is some work needed using a `custom-webpack` builder to get things going.

README.md

@@ -19,29 +19,31 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu
 ## Table of contents
 
 * [Quick start options](#quick-start-options)
-* [Modules](#modules)
-* [Building plotly.js](#building-plotlyjs)
+* [Partial bundles](#partial-bundles)
+* [Alternative ways to require or build plotly.js](#alternative-ways-to-require-or-build-plotlyjs)
 * [Bugs and feature requests](#bugs-and-feature-requests)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
 * [Community](#community)
-* [Notable Contributors](#creators)
+* [Versioning](#versioning)
+* [Notable contributors](#creators)
 * [Copyright and license](#copyright-and-license)
 
+---
 ## Quick start options
 
 ### Install with npm
 
 ```sh
-npm install plotly.js-dist
+npm install plotly.js-dist-min
 ```
 
 and import plotly.js as
 
 ```js
-import Plotly from 'plotly.js-dist'
+import Plotly from 'plotly.js-dist-min'
 // Or using require,
-var Plotly = require('plotly.js-dist')
+var Plotly = require('plotly.js-dist-min')
 ```
 
 ### Use the plotly.js CDN hosted by Fastly
@@ -70,88 +72,119 @@ and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly
 
 #### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples.
 
+---
 ## Partial bundles
 
 There are two kinds of plotly.js partial bundles:
 1. The official partial bundles that are distributed to `npm` and the CDN, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
 2. Custom bundles you can create yourself, if none of the distributed packages meet your needs.
 
 Use the `traces` option to include just the trace types you need.
-```
+```sh
 npm run partial-bundle -- --traces scatter,scattergl,scatter3d
 ```
 Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
 [This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.
 
 By default all transforms are included in the bundle.
 Use the `transforms` option to specify which should be included.
-```
+```sh
 npm run partial-bundle -- --transforms sort,filter
 ```
 
 Or use `transforms none` to exclude them all.
-```
+```sh
 npm run partial-bundle -- --transforms none
 ```
 
 Use the `out` option to change the bundle filename (default `custom`).
 The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
-```
+```sh
 npm run partial-bundle -- --out myBundleName
 ```
 
 Use the `unminified` option to disable compression.
-```
+```sh
 npm run partial-bundle -- --unminified
 ```
 
 ### Example illustrating use of different options together
 To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
-```
+```sh
 npm run partial-bundle -- \
     --unminified \
     --out myScatters \
     --traces scatter,scattergl,scatter3d \
     --transforms none
 ```
 Or simply on one line:
-```
+```sh
 npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
 ```
 
-## Building plotly.js
-
-Building instructions using `webpack`, `browserify` and other build frameworks are in [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md)
+---
+## Alternative ways to require or build plotly.js
+If your library needs to bundle or directly require [plotly.js/lib/index.js](https://github.com/plotly/plotly.js/blob/master/lib/index.js) or parts of its modules similar to [index-basic](https://github.com/plotly/plotly.js/blob/master/lib/index-basic.js) in some other way than via an official or a custom bundle, or in case you want to tweak the default build configurations of `browserify` or `webpack`, etc. then please visit [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md).
 
+---
 ## Bugs and feature requests
 
 Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md)
 
+---
 ## Documentation
 
 Official plotly.js documentation is hosted at [https://plotly.com/javascript](https://plotly.com/javascript).
 
 These pages are generated by the Plotly [graphing-library-docs repo](https://github.com/plotly/graphing-library-docs) built with [Jekyll](https://jekyllrb.com/) and publicly hosted on GitHub Pages.
 For more info about contributing to Plotly documentation, please read through [contributing guidelines](https://github.com/plotly/graphing-library-docs/blob/master/README.md).
 
+### To support MathJax
+
+*Before* the plotly.js script tag, add:
+
+```html
+<script src="mathjax/MathJax.js?config=TeX-AMS-MML_SVG"></script>
+```
+
+You can get the relevant MathJax files from the internet e.g.
+"https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"
+
+By default, plotly.js will modify the global MathJax configuration on load.
+This can lead to undesirable behavior if plotly.js is loaded alongside
+other libraries that also rely on MathJax. To disable this global configuration
+process, set the `MathJaxConfig` property to `'local'` in the `window.PlotlyConfig`
+object.  This property must be set before the plotly.js script tag, for example:
+
+```html
+<script>
+   window.PlotlyConfig = {MathJaxConfig: 'local'}
+</script>
+<script src="plotly.min.js"></script>
+```
+
+---
 ## Contributing
 
 Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development.
 
+---
 ## Community
 
 * Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
 * Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
   on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
 * Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly).
 
+---
 ## Versioning
 
 This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).
 
 See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
 
-## Notable Contributors
+---
+## Notable contributors
 
 Plotly.js is at the core of a large and dynamic ecosystem with many contributors who file issues, reproduce bugs, suggest improvements, write code in this repo (and other upstream or downstream ones) and help users in the Plotly community forum. The following people deserve special recognition for their outsized contributions to this ecosystem:
 
@@ -160,7 +193,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
 |**Alex C. Johnson**| [@alexcjohnson](https://github.com/alexcjohnson) | | Active, Maintainer |
 |**Mojtaba Samimi** | [@archmoj](https://github.com/archmoj) | [@solarchvision](https://twitter.com/solarchvision) | Active, Maintainer |
 |**Antoine Roy-Gobeil** | [@antoinerg](https://github.com/antoinerg) | | Active, Maintainer |
-|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active |
+|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active, Maintainer |
 |**Jon Mease** | [@jonmmease](https://github.com/jonmmease) | [@jonmmease](https://twitter.com/jonmmease) | Active |
 |**Étienne Tétreault-Pinard**| [@etpinard](https://github.com/etpinard) | [@etpinard](https://twitter.com/etpinard) | Hall of Fame |
 |**Mikola Lysenko**| [@mikolalysenko](https://github.com/mikolalysenko) | [@MikolaLysenko](https://twitter.com/MikolaLysenko) | Hall of Fame |
@@ -175,6 +208,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
 |**Chris Parmer**| [@chriddyp](https://github.com/chriddyp) | | Hall of Fame |
 |**Alex Vados**| [@alexander-daniel](https://github.com/alexander-daniel) | | Hall of Fame |
 
+---
 ## Copyright and license
 
 Code and documentation copyright 2021 Plotly, Inc.