Skip to content
Branch: master
Find file History
Type Name Latest commit message Commit time
Failed to load latest commit information.
3d initial repo setup Jan 28, 2020
chart-events initial repo setup Jan 28, 2020
legacy/polar initial repo setup Jan 28, 2020
2015-07-21-plotlyjs-getting-started.html initial repo setup Jan 28, 2020 initial repo setup Jan 28, 2020 fixups in response to review Jan 31, 2020

Contribute to Plotly's JavaScript Documentation

Plotly welcomes contributions to its open-source JavaScript graphing libraries documentation from its community of users.

Our JavaScript tutorials are written in HTML files in the _posts/plotly_js directory of this repository.

Contribute Quickly to Plotly's JavaScript Graphing Library Documentation

To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest. This can be done using the GitHub graphical user interface at

The easiest way to do this is to follow the Edit this page on GitHub link at the top right of the page you are interested in contributing to:

Screen Shot 2020-01-07 at 12 45 39 PM

You don't have to worry about breaking the site when you submit a pull request! This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request in order to ensure that it definitely increases the health of Plotly's graphing libraries codebase.

Develop Locally

For contributions such as new example posts, we recommend setting up a local development environment so that you can test your changes as you work on them.

See the How To Get The Application Working Locally section of the Contributing Guide to learn how to clone this repository to your local development environment and install its dependencies.

Then follow these instructions to create or modify a new post. If the post is the first of its chart type, you need to create an index page for it first.

Create An Index Page For A New Chart Type:

If you are documenting a new chart type, then you need to create an index page for it before creating the actual example page.

  1. In documentation/_posts/plotly_js, create a folder titled with the chart type or topic you're adding to the documentation (i.e. bar).

  2. cd into the folder you created and create an HTML index file for the chart type named: yyyy-mm-dd-chart_type_plotly_js_index.html. Copy the index file template below. Make sure to replace placeholder text!

name: Add-Chart-Type-or-Topic
permalink: javascript/add-chart-type-or-topic/
description: How to make a D3.js-based add-chart-type-or-topic in javascript. Add an additional sentence summarizing chart-type or topic.
layout: langindex
thumbnail: thumbnail/mixed.jpg 
language: plotly_js
page_type: example_index
display_as: **SEE BELOW
order: 5
  {% assign examples = site.posts | where:"language","plotly_js" | where:"suite","add-chart-type-or-topic"| sort: "order" %}
  {% include posts/auto_examples.html examples=examples %}
  • Make sure to update _includes/posts/documentation_eg.html with the new chart type!

  • Index pages for chart categories must have order: 5.

Create A New Example Post:

  1. In the folder containing the examples for the chart type you are writing documenation for, create a file named: yyyy-mm-dd-example-title.html.

  2. Copy the example post template below and write JavaScript code to demonstrate the feature you are documenting.

  • If plot_url front-matter is not present, then the resulting chart will be displayed inline and a Try It Codepen button will be automatically generated.
  • If plot_url front-matter is present, then the URL given will be embedded in an iframe below the example.
description: How to make a D3.js-based bar chart in javascript. Seven examples of
grouped, stacked, overlaid, and colored bar charts.
display_as: basic
language: plotly_js
layout: base
name: Bar Charts
order: 3
page_type: example_index
permalink: javascript/bar-charts/
redirect_from: javascript-graphing-library/bar-charts/
thumbnail: thumbnail/bar.jpg **MORE INFO ON ADDING THUMBNAILS BELOW
markdown_content: |
  indented content in markdown format which will prefix an example ****SEE BELOW
var data = [
    x: ['giraffes', 'orangutans', 'monkeys'],
    y: [20, 14, 23],
    type: 'bar'

Plotly.newPlot('myDiv', data);

Modify An Existing Post:

  1. Find the post you want to modify in _posts/plotly_js. Then, open the HTML file that contains that post and modify either the front-matter or the JavaScript.

Best Practices:

  • order examples from basic to advanced
  • avoid the use of global JavaScript variables for data and layout.
  • make the chart display in a DOM element named myDiv
  • use the .newPlot() function
  • use "real" data to make the examples realistic and useful for users.
    • avoid using random or dummy data as much as humanly possible! Should only be a last resort.
  • upload data files to as importing data rather than pasting a large chunk of data in the tutorial creates a cleaner example.
  • use var config = {mapboxAccessToken: "your access token"}; if your chart requires Mapbox authentication. "your access token will replaced by Plotly's private token at build time. In development mode, you will need to create a _data/mapboxtoken.yml file and paste Plotly's non-URL restricted Mapbox key into it. This is available in 1Password.

Make a Pull Request

  • Ready for your changes to be reviewed? Make a pull request!

    • Create a feature branch and use git status to list changed files.
    git checkout -b your_feature_branch
    git status
    • Add, commit, and push the files that you'd like to add to your PR:
    git add file-a
    git add file-b
    git commit -m 'message about your changes'
    git push origin your_feature_branch
    • Visit the documentation repo and open a pull request!. You can then tag @jdamiba for a review.

Style Edits

Please refer to our Styles README

Thanks for contributing to our documentation!!

You can’t perform that action at this time.