Merge pull request #7609 from daexs/mkdocs-conversion

Includes code for the new documentation build using Mkdocs.

Author: daexs

.gitignore

@@ -1,4 +1,7 @@
 node_modules
+_site
+
+__pycache__
 
 build/*
 !build/plotcss.js
@@ -17,3 +20,6 @@ tags
 !.github/
 !.gitignore
 !.npmignore
+
+docs/tmp/
+docs/build/

BUILDING.md

@@ -12,11 +12,11 @@ environment for doing development and running tests.
 Please check out our [Code of Conduct](code_of_conduct.md). Don't tl:dr; it
 but the general idea is to be nice.
 
-## Plotly.js vs Plotly.py and Plotly.R
+## Plotly.js vs Plotly.py
 
-[Plotly.js](https://plotly.com/javascript) is a standalone Javascript data visualization library, and it also powers the Python and R modules named `plotly` in those respective ecosystems (referred to as [Plotly.py](https://plotly.com/python) and [Plotly.R](http://plotly.com/r), respectively, for clarity). There also exist Plotly.js-powered libraries for other languages such as Julia, Scala, Rust, .NET and even C++!
+[Plotly.js](https://plotly.com/javascript) is a standalone Javascript data visualization library, and it also powers the Python module named `plotly` (referred to as [Plotly.py](https://plotly.com/python) for clarity).
 
-The basic architecture of Plotly.js is to accept [JSON](https://json.org/) representation of figures that adhere to the [figure schema](https://plotly.com/javascript/reference/index/) and draw interactive graphical representations of these figures in a browser. Libraries in other languages like Python and R provide idiomatic interfaces for users of those languages to create and manipulate these JSON structures, and arrange for them to be rendered in a browser context by Plotly.js. This means that in many cases, when a Python or R user wishes to add a feature to the library they know as `plotly`, the relevant changes must be implemented in Plotly.js, in this repo.
+The basic architecture of Plotly.js is to accept [JSON](https://json.org/) representation of figures that adhere to the [figure schema](https://plotly.com/javascript/reference/index/) and draw interactive graphical representations of these figures in a browser. The Python library provides an idiomatic interface for Python users to create and manipulate these JSON structures, and arrange for them to be rendered in a browser context by Plotly.js. This means that in many cases, when a Python user wishes to add a feature to the library they know as `plotly`, the relevant changes must be implemented in Plotly.js, in this repo.
 
 ## How do changes get made to Plotly.js?
 
@@ -37,7 +37,8 @@ The basic process for adding new features or fixing bugs is as follows. Please n
 The current Plotly.js maintainers are all employees of Plotly (the company) and one of their primary responsibilities is ensuring the process above runs smoothly. It is worth noting that maintainers and non-maintainer Plotly employees all follow the process above: proposing changes, iterating on proposals and eventually developing and reviewing each other's pull requests. As mentioned above, maintainers look after bug fixes, performance, security, documentation and concerns that impact the long-term prospects for this library.  In terms of development work, maintainers tend to prioritize issues that do or are likely to impact Plotly customers, as well as on [sponsored features or bug fixes](https://plot.ly/products/consulting-and-oem/). Sponsored work proceeds via the process listed above, albeit with the option of conducting portions of the "discussion" step in a confidential setting if desired. Please note that maintainers are happy and eager to help with community-led pull requests, independent of customer-driven development priorities :)
 
 ### The Plotly.js Community
-The Plotly.js community, construed fairly broadly, includes the maintainers and all users of Plotly.js and associated projects ([Plotly.py](https://plotly.com/python), [Dash](https://dash.plotly.com/), [Plotly.R](https://plotly.com/r), [Chart Studio](https://plotly.com/chart-studio) and many others). The community includes people from any background, domain, affiliation and level of technical expertise, for example (but not limited to!) employees of small or large companies or startups; employees or students of universities or other educational institutions; government employees and contractors; employees and volunteers of non-profits; individual hobbyists etc.
+
+The Plotly.js community, construed fairly broadly, includes the maintainers and all users of Plotly.js and associated projects ([Plotly.py](https://plotly.com/python), [Dash](https://dash.plotly.com/), and others supported by the open source community). The community includes people from any background, domain, affiliation and level of technical expertise, for example (but not limited to!) employees of small or large companies or startups; employees or students of universities or other educational institutions; government employees and contractors; employees and volunteers of non-profits; individual hobbyists etc.
 
 **Anyone in the community is encouraged to contribute to every step of the process described above!**  Creating issues to report bugs or suggest new behaviours is a valuable contribution to this project, as is proposing a concrete set of changes to address issues created by anyone at any time. In  the same way, giving feedback on proposals created by anyone in the community is valuable, as is, of course, development and review work. [Proposing changes to the documentation of Plotly.js or associated projects](https://github.com/plotly/graphing-library-docs/blob/master/README.md) is an extremely valuable form of contribution, as is [asking or answering questions on our community forum](https://community.plotly.com/), as it creates a record of a question and discussion, which others can stumble across later and use to further their own work.
 

code_of_conduct.md renamed to CODE_OF_CONDUCT.md

@@ -22,22 +22,20 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu
   </a>
 </div>
 
+## Table of Contents
 
-## Table of contents
-
-* [Load as a node module](#load-as-a-node-module)
-* [Load via script tag](#load-via-script-tag)
+* [Load as a Node Module](#load-as-a-node-module)
+* [Load via Script Tag](#load-via-script-tag)
 * [Bundles](#bundles)
-* [Alternative ways to load and build plotly.js](#alternative-ways-to-load-and-build-plotlyjs)
 * [Documentation](#documentation)
-* [Bugs and feature requests](#bugs-and-feature-requests)
+* [Bugs and Feature Requests](#bugs-and-feature-requests)
 * [Contributing](#contributing)
-* [Notable contributors](#notable-contributors)
+* [Notable Contributors](#notable-contributors)
 * [Copyright and license](#copyright-and-license)
 * [Community](#community)
 
----
-## Load as a node module
+## Load as a Node Module
+
 Install [a ready-to-use distributed bundle](https://github.com/plotly/plotly.js/blob/master/dist/README.md)
 ```sh
 npm i --save plotly.js-dist-min
@@ -54,10 +52,10 @@ var Plotly = require('plotly.js-dist-min')
 
 You may also consider using [`plotly.js-dist`](https://www.npmjs.com/package/plotly.js-dist) if you prefer using an unminified package.
 
----
-## Load via script tag
+## Load via Script Tag
+
+### The `script` HTML Element
 
-### The script HTML element
 > In the examples below `Plotly` object is added to the window scope by `script`. The `newPlot` method is then used to draw an interactive figure as described by `data` and `layout` into the desired `div` here named `gd`. As demonstrated in the example above basic knowledge of `html` and [JSON](https://en.wikipedia.org/wiki/JSON) syntax is enough to get started i.e. with/without JavaScript! To learn and build more with plotly.js please visit [plotly.js documentation](https://plotly.com/javascript).
 
 ```html
@@ -77,6 +75,7 @@ You may also consider using [`plotly.js-dist`](https://www.npmjs.com/package/plo
 ```
 
 Alternatively you may consider using [native ES6 import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) in the script tag.
+
 ```html
 <script type="module">
     import "https://cdn.plot.ly/plotly-3.2.0.min.js"
@@ -87,15 +86,19 @@ Alternatively you may consider using [native ES6 import](https://developer.mozil
 Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>.
 
 ### Un-minified versions are also available on CDN
+
 While non-minified source files may contain characters outside UTF-8, it is recommended that you specify the `charset` when loading those bundles.
+
 ```html
 <script src="https://cdn.plot.ly/plotly-3.2.0.js" charset="utf-8"></script>
 ```
 
 > Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.5. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
 
 ### MathJax
+
 You could load either version two or version three of MathJax files, for example:
+
 ```html
 <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
 ```
@@ -108,40 +111,36 @@ You could load either version two or version three of MathJax files, for example
 Please refer to `devtools/test_dashboard/index-mathjax3chtml.html` to see an example.
 
 ### Need to have several WebGL graphs on a page?
+
 You may simply load [virtual-webgl](https://github.com/greggman/virtual-webgl) script for WebGL 1 (not WebGL 2) before loading other scripts.
+
 ```html
 <script src="https://unpkg.com/[email protected]/src/virtual-webgl.js"></script>
 ```
 
 ## Bundles
+
 There are two kinds of plotly.js bundles:
+
 1. Complete and partial official 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 to optimize the size of bundle depending on your needs. Please visit [CUSTOM_BUNDLE](https://github.com/plotly/plotly.js/blob/master/CUSTOM_BUNDLE.md) for more information.
 
----
-## Alternative ways to load and build plotly.js
-If your library needs to bundle or directly load [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, then please visit [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.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).
 
----
-## Bugs and feature requests
+## 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)
 
----
 ## 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.
 
----
-## 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:
 
@@ -171,7 +170,6 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
 |**Alex Vados**| [@alexander-daniel](https://github.com/alexander-daniel) | Hall of Fame |
 |**Mojtaba Samimi** | [@archmoj](https://github.com/archmoj) | Hall of Fame |
 
----
 ## Copyright and license
 
 Code and documentation copyright 2025 Plotly, Inc.
@@ -184,7 +182,6 @@ This project is maintained under the [Semantic Versioning guidelines](https://se
 
 See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
 
----
 ## Community
 
 * Follow us on [X](https://x.com/plotlygraphs) and [LinkedIn](https://www.linkedin.com/company/plotly/) for the latest Plotly news.