Skip to content

Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README #5705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 3, 2021
Merged

Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README #5705

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
66b80c0
revise README
archmoj Jun 2, 2021
a0bd258
revise readme
archmoj Jun 2, 2021
866ca5a
reorder items
archmoj Jun 2, 2021
fadac71
place mathjax note close to cdn
archmoj Jun 2, 2021
394d9f4
point to bundles - simplify dist/README
archmoj Jun 3, 2021
9d929b3
move up dist-min
archmoj Jun 3, 2021
4da8c59
revise stats and cleanup extra info
archmoj Jun 3, 2021
4bc79dd
rename and use dist in function and variable names
archmoj Jun 3, 2021
a2bccfd
add npm and CDN links for main bundles
archmoj Jun 3, 2021
d6b5498
add CUSTOM_BUNDLE file, how to install deps, more edits
archmoj Jun 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 48 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,58 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu

## Table of contents

* [Quick start options](#quick-start-options)
* [Load from CDN](#load-from-cdn)
* [Load from npm](#load-from-npm)
* [Versioning](#versioning)
* [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)
* [Versioning](#versioning)
* [Notable contributors](#creators)
* [Copyright and license](#copyright-and-license)

---
## Quick start options
## Load from CDN
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would spell out "Content Delivery Network (CDN)"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a0bd258.

Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>.

### Minified plotly.js X.Y.Z bundles
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rename this "Usage example"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a0bd258.

```html
<head>
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
</head>
<body>
<div id="gd"></div>

<script>
Plotly.newPlot("gd", {
"data": [{
"y": [1, 2, 3]
}],
"layout": {
"width": 600,
"height": 400
}
});
</script>
</body>
```
In the example above `Plotly` object is added to the window scope by the script in the `head` section.
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).

### 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-2.0.0-rc.2.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.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for little "notes" like this, please don't use #### but rather prefix them with > so they get indented/dimmed a bit.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a0bd258.


### Install with npm

## Load from npm
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have this be first

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a0bd258.


```sh
npm install plotly.js-dist-min
Expand All @@ -42,37 +79,19 @@ and import plotly.js as

```js
import Plotly from 'plotly.js-dist-min'
// Or using require,
var Plotly = require('plotly.js-dist-min')
```

### Use the plotly.js CDN hosted by Fastly

#### A minified plotly.js X.Y.Z release
```html
<script src="https://cdn.plot.ly/plotly-1.58.4.min.js" charset="utf-8"></script>
```

#### An un-minified version is also available
```html
<script src="https://cdn.plot.ly/plotly-1.58.4.js" charset="utf-8"></script>
Or
```js
var Plotly = require('plotly.js-dist-min')
```

and use the `Plotly` object in the window scope.

##### 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.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.

Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>

### Download the latest release or a release candidate (rc)

[Latest and rc releases on GitHub](https://github.com/plotly/plotly.js/releases/)
---
## Versioning
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This probably doesn't need to be a top-level item, just a little note somewhere, maybe under the NPM section. it's kind of the norm anyway.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a0bd258.


and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).

#### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples.
See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.

---
## Partial bundles

There are two kinds of plotly.js partial bundles:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could we maybe define what a partial bundle is and why we talk about them?

Expand Down Expand Up @@ -159,13 +178,6 @@ Please read through our [contributing guidelines](https://github.com/plotly/plot
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

Expand Down