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

This repository mainly serves:

• Plotly's graphing libraries documentation index page at https://plotly.com/graphing-libraries.

• Plotly's JavaScript graphing library documentation at https://plotly.com/javascript

  • Please be aware that only the content of Plotly's JavaScript graphing library documentation (hosted at https://plotly.com/javascript) is contained in this repository. You can find the content in the _posts/plotly_js directory.
  • For information about editing plotly.js documentation click here.

• Plotly's Python graphing library documentation at https://plotly.com/python

  • The content for Plotly's Python graphing library documentation (hosted at https://plotly.com/python) IS NOT contained in this repository. It is contained in the plotly.py repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time.
  • For information about editing plotly.py documentation click here.

• Plotly's R graphing library documentation at https://plotly.com/r

  • The content for Plotly's R graphing library documentation (hosted at https://plotly.com/r) IS NOT contained in this repository. It is contained in the plotly.r-docs repository at https://github.com/plotly/plotly.r-docs/ and is cloned into this repository at build time.
  • For information about editing Plotly's R documentation click here.

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.

The easiest way to do this is to follow the Suggest an edit to this page link at the top right of the page you are interested in contributing to:

Note: 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.

For more extensive changes to Plotly's JavaScript documentation, we suggest getting the Jekyll application which builds the site to run locally so that you can test your changes as you develop them.

This involves cloning the repository and installing its dependencies: Git, Ruby, and the Python packages used by the CI scripts.

Note: Some older subdependencies need to be built from source on Windows, which is difficult or in some cases not possible.

To run this application locally:

1. Use Git to clone this repository:

git clone git@github.com:plotly/graphing-library-docs.git
cd graphing-library-docs

Running git status in your terminal should then output the following:

On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

2. Install Ruby 2.7.4. We recommend using rbenv. (RVM tries to fetch openssl 1.1 which has been disabled, but if you already have openssl 1.1, then RVM should work):

rbenv install 2.7.4

Running ruby --version should output ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23).

3. Install all remaining dependencies (Ruby gems, Python packages, Node packages, and upstream tutorial content) in one step:

make setup

If you'd rather install each piece manually, run these instead:

gem install bundler && bundle install      # Ruby gems (installs Jekyll)
pip install -r requirements.txt            # Python packages
npm install                                # Node packages (for the gulp/scss workflow)
make fetch_upstream_files                  # Python, R, Julia, Matlab, C#, and F# tutorial content

4. Serve the Jekyll application (the initial build may take a while): bundle exec jekyll serve --incremental --config _config_dev.yml.

If you get an error due to a missing package, install the package manually with gem install <package>, then restart your terminal.

5. Visit the pages at: http://localhost:4000/

Note: The default development configuration (_config_dev.yml) excludes _posts/plotly_js and _posts/python-v3 for faster builds. If you want to include or exclude different folders, copy _config_dev.yml, rename it _config_personal.yml, and modify the exclude statement.

• If you name the Jekyll configuration file _config_personal.yml, it will be caught by the .gitignore file and not committed to version control.

• Run bundle exec jekyll serve --incremental --config _config_personal.yml to use the custom configuration file

• Example configuration that loads only the JavaScript posts:

# ---
# Excludes every directory except JavaScript
# ---
exclude: ['_posts/reference_pages', '_posts/ggplot2', '_posts/julia', '_posts/matlab', '_posts/node_js', '_posts/r', '_posts/python', '_posts/python-v3', '_posts/misc', '_posts/dashboards', '_posts/scala', '_posts/nodejs', 'node_modules']

• Example configuration that loads every directory:

# ---
# Excludes no directory
# ---
staticurl: http://localhost:4000/all_static
exclude: []

Note The Python, R, Julia, Matlab, C#, and F# tutorial content is not stored in this repository—it is cloned in at build time from upstream repos by make fetch_upstream_files. If you want those pages to render locally, run make fetch_upstream_files before serving.

Whenever a pull request is made, the GitHub Actions workflow defined in .github/workflows/build.yml runs. It:

• runs front-matter-ci.py to validate YAML front-matter
• runs check-or-enforce-order.py against each tutorial directory to validate the order field
• builds the site with bundle exec jekyll build
• captures Percy snapshots for visual regression review

Making sure that a pull request passes every CI check is part of the code review process.

Search on plotly.com docs pages is powered by Algolia indexes that are updated separately from the site build. There are four indexes, each updated by its own make target:

You can browse the indexes at https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/.

When to update: Run the appropriate update_*_search target whenever a new tutorial is added to the corresponding _posts/ directory. Run the schema index update command when a new plotly.js version is released.

How to exclude files from an index: Each search index has its own Jekyll config (_config_python_search.yml, _config_r_search.yml, etc.) with an algolia.excluded_files list. Add files or paths there to keep them out of search results.

Algolia API key: Updating the indexes requires a private Algolia API key set as an environment variable. Request it from a Plotly maintainer via an issue on this repository.

Run make help to see all available make targets, including search-index and upstream-fetch commands.

This repository also contains:

• Plotly's Node.js, Scala, and Python V3 graphing libraries documentation
• the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries
• landing/index pages for the Python, R, ggplot2, Julia, Matlab, C#, and F# docs (the tutorial content for those languages is fetched from upstream repos at build time)