Skip to content

plotly_js

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

plotly_js

README.md

Contribute to Plotly's Javascript Documentation

Initial Steps:

  1. Clone the repo and then check out the source-design-merge branch:
$ git clone [email protected]:plotly/documentation.git
$ git fetch origin
$ git checkout source-design-merge

  1. Check Ruby version $ ruby --version. We recommend using the same ruby version as gh-pages: https://pages.github.com/versions/. Note RVM is helpful for installing and managing ruby versions.

  2. Install bundler and a couple dependencies from the gemfile:

$ gem install bundler
$ bundle install

IMPORTANT -If not using bundler and the gemfile, install the same jekyll version that Github Pages is using.

Create Plotly.js Documentation:

Our javascript tutorials are written in HTML files with embeded codepen examples.

In documentation/_posts/plotly_js
  1. 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 labeled: yyyy-mm-dd-chart_type_plotlyjs_index.html. Copy the index file template below and replace with the necessary information pertaining to the doc you are creating.
---
title: Javascript Graphing Library D3.js-based Add-Chart-Type-or-Topic | Examples | Plotly
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: base
has_thumbnail: true
thumbnail: thumbnail/add-chart-type-or-topic.jpg *MORE INFO ON ADDING THUMBNAILS BELOW
language: plotly_js
page_type: example_index
display_as: **SEE BELOW
order: ***SEE BELOW
markdown_content: |
  indented content in markdown format which will prefix an example ****SEE BELOW
---
{% assign examples = site.posts | where:"language","plotly_js" | where:"suite","add-chart-type-or-topic"**** | sort: "order" %}
{% include auto_examples.html examples=examples %}

  1. Create a Codepen example. Use Plotly's Codepen account to create an example that clearly demonstrates the feature that you're discussing in the doc.

  2. Add an HTML file for each example with the codepen example embedded within. The codepen example must be embedded with https (not http). The HTML file should have a header (template below), followed by the javascript code used in the codepen example.

---
name: Basic Bar Chart **
plot_url: https://codepen.io/plotly/embed/74a638752a41ac9672a05f628e4ddaff/?height=500&theme-id=15263&default-tab=result
language: plotly_js
suite: bar
order: 1 **
sitemap: false
arrangement: horizontal
---
var data = [
  {
    x: ['giraffes', 'orangutans', 'monkeys'],
    y: [20, 14, 23],
    type: 'bar'
  }The
];

Plotly.newPlot('myDiv', data);
  1. Best Practices:
  • Set plot_url: to the embedded codepen example with the default-tab=result
  • Now we have an awesome navigation bar on the left side of our tutorial pages. The navigation bar displays the name** in the order** so add a name for each example and try to make names as informative and concise as possible. Ex: Basic Bar Chart
  • order examples from basic -> advanced.
  • Try to use "real" data, to make the examples realistic and interesting. Avoid including large datablocks in the tutorial by uploading the datafile to https://github.com/plotly/datasets. Importing data rather than pasting a large chunk of data in the tutorial creates a cleaner example. (Using random data is okay for some examples too :) )
  1. Add Thumbnail Images
  • Thumbnail images should named your-tutorial-chart.jpg and be EXACTLY 160px X 160px
  • Thumbnail images should be clear and interesting. You do not need to capture the ENTIRE chart, but rather focus on the most interesting part of the chart.
  • Use images.plot.ly for adding new images.
    • Log-in here: https://661924842005.signin.aws.amazon.com/console
    • Username: Plotly_Editors
    • From the Amazon Web Services Console select S3 (Scalable Storage in the Cloud) then select plotly-tutorials -> plotly-documentation -> thumbnail
    • Now from All Buckets /plotly-tutorials/plotly-documentation/thumbnail select the Actions dropdown and upload your .jpg file
In the terminal in the documentation repo
  1. Make a PR
  • Ready for your changes to be reviewed? Make a pull request against the source-design-merge branch! 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 against the source-design-merge branch. You can then tag @cldougl and @bcdunbar for a review.
  1. To proof your work follow these steps: https://github.com/plotly/documentation/blob/source/Contributing.md#rendering-the-pages-locally
At https://plot.ly/javascript
  1. Your changes haven't been deployed yet so they won't be online. That said, PLEASE visit https://plot.ly/javascipt/your-tutorial and make sure everything looks correct once they have been deployed by either @cldougl or @bcdunbar.
  • Some common problems that you should check for:
    • Make sure all plots/codepen embeds appear! (*you may want to sign out of your Plotly/codepen account to ensure you didn't accidentally embed private plots)
    • The thumbnail image appears on: https://plot.ly/javascript/

Search

We now have search via algolia implemented on our index and reference documentation pages! Please refer to our make README for more information on how search works and instructions on how to update or edit Plotly search indices.

Thanks for contributing to our documentation!!