Skip to content

docs: Update build docs and clarify instructions #438

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
camdecoster merged 3 commits into from
May 19, 2026
Merged

docs: Update build docs and clarify instructions #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6341ac1
docs: Update build docs and clarify instructions
camdecoster May 18, 2026
68a7bd1
Update image in README.md
camdecoster May 19, 2026
436808c
Address PR feedback
camdecoster May 19, 2026
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
82 changes: 51 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,17 @@ This repository mainly serves:

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 `Edit this page on GitHub` link at the top right of the page you are interested in contributing to:
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:

![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)
![Bar charts in JavaScript](https://github.com/user-attachments/assets/2835bbba-19e9-4f6c-b550-2b75730f9d21)

**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.
**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.
Copy link
Copy Markdown
Contributor

@red-patience red-patience May 19, 2026

Choose a reason for hiding this comment

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

I think this goes without saying! 😅


## How To Get The Application Working Locally

For more extensive changes to Ploty'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.
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](https://git-scm.com/), [Ruby]((https://www.ruby-lang.org/en/), [Jekyll](https://jekyllrb.com/), and the [Python `requests` package](https://pypi.org/project/requests/).
This involves cloning the repository and installing its dependencies: [Git](https://git-scm.com/), [Ruby](https://www.ruby-lang.org/en/), and the Python packages used by the CI scripts.

1. Use [`git`](https://git-scm.com/) to [clone](https://git-scm.com/docs/git-clone) the public `plotly/graphing-library-docs` repository.

Expand All @@ -60,42 +60,41 @@ Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
```

2. Download Ruby and check your `Ruby` version by running the `ruby --version` command in your terminal.
2. Install Ruby 2.7.4. Check your version with `ruby --version`. [RVM](https://rvm.io/rvm/install) is helpful for installing and managing Ruby versions.

**Note:** We recommend using `version 2.7.4`, the same ruby version as [gh-pages](https://pages.github.com/versions/). Note [RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions.
3. Install all remaining dependencies (Ruby gems, Python packages, Node packages, and upstream tutorial content) in one step:

3. Download Jekyll and check your Jekyll version by running the `jekyll -v` command in your terminal. We recommend using the same ruby version as [gh-pages](https://pages.github.com/versions/).
```sh
make setup
```

4. Install bundler and dependencies from the Jekyll applicaton's [`Gemfile`](https://github.com/plotly/graphing-library-docs/blob/master/Gemfile) by running the following commands in your terminal:
If you'd rather install each piece manually, run these instead:

```sh
gem install bundler
bundle install
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
```

**Note:** These dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using.
4. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.

5. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.
5. Visit the pages at: [http://localhost:4000/](http://localhost:4000)

6. Visit the pages at: [http://localhost:4000/](http://localhost:4000)

**Note** The default Jekyll configuration file only builds the JavaScript posts by [excluding folders](https://jekyllrb.com/docs/configuration/options/). If you want to override this behavior, serve the application with a custom Jekyll configuration file in the root of the repository. Do this by copying `_config_dev.yml`, renaming it `_config_personal.yml`, and modifying the `exclude` statement.
**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 --config _config_personal.yml` to use the custom configuration file

- Example configuration:
- Example configuration that loads **only** the JavaScript posts:
```yml
# ---
# 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']
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']
```

and you'll only load the files in `_posts/plotly_js` directory because that is the only directory that is not excluded.

Change it to this:

- Example configuration that loads **every** directory:
```yml
# ---
# Excludes no directory
Expand All @@ -104,21 +103,42 @@ staticurl: http://localhost:4000/all_static
exclude: []
```

and you'll load every file because no directories are excluded.
**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.

## Continuous Integration

Whenever a pull request is made, a continuous integration workflow is initiated. This includes of:
- running the `check-or-enforce-order.py` and `front-matter-ci.py` scripts inside of a Docker container to validate YAML front-matter
- Percy screenshot testing
Whenever a pull request is made, the GitHub Actions workflow defined in [`.github/workflows/build.yml`](https://github.com/plotly/graphing-library-docs/blob/master/.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 indexes

Making sure that a pull request passes every continuous integration test is a 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:

**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/graphing-library-docs/blob/master/.circleci/config.yml.**
| Index | Search on | Update with |
| --- | --- | --- |
| `js_docs` | https://plotly.com/javascript/ | `make update_js_search` |
| `python_docs` | https://plotly.com/python/, https://plotly.com/pandas/ | `make update_python_search` |
| `r_docs` | https://plotly.com/r/, https://plotly.com/ggplot2/ | `make update_r_search` |
| `schema` | reference pages (e.g. https://plotly.com/python/reference) | `make update_ref_search` |

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.
Copy link
Copy Markdown
Contributor

@red-patience red-patience May 19, 2026

Choose a reason for hiding this comment

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

Hm, why would we want to keep stuff out of search results?

Copy link
Copy Markdown
Contributor Author

@camdecoster camdecoster May 19, 2026

Choose a reason for hiding this comment

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

Looking at the referenced python YML file, it excludes anything to do with other libraries like plotly.js, plotly.r, etc.


**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.

## Other Documentation

This repository also contains:
- Plotly's Node.js, Matlab, Scala, Julia, and Python V3 graphing libraries documentation
- the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries.

- 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)
117 changes: 13 additions & 104 deletions _posts/julia/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,114 +1,23 @@
# Contribute to Plotly's [Julia Documentation](https://plotly.com/julia/)
## Initial Steps:
0. Clone the repo.:

```
$ git clone git@github.com:plotly/graphing-library-docs.git
$ cd graphing-library-docs
```
1. Check Ruby version `$ ruby --version`. We recommend using `version 2.3.3` or the same ruby version as gh-pages: https://pages.github.com/versions/. Note [RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions.
The Julia tutorial content displayed on https://plotly.com/julia/ is **not** authored in this repository. It lives in [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs) and is fetched into this repo at build time by `make fetch_upstream_files`.

2. Install bundler and a couple dependencies from the gemfile:
## Where to make changes

```
$ gem install bundler
$ bundle install
- **Tutorial content (chart examples, prose, etc.):** edit the source files in [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs). See that repo's README for authoring instructions.
- **The Julia landing/index pages** that appear on https://plotly.com/julia/ (sidebar, categories, etc.): edit the corresponding files in this repository under `_posts/julia/` and the include files under `_includes/`.

```
<b>IMPORTANT</b> -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/).
## Building locally

## Create Julia Documentation:
Our Julia tutorials are written in HTML files with embedded plot examples.
##### In `documentation/_posts/julia`
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_julia_index.html`. Copy the index file template below and replace with the necessary information pertaining to the doc you are creating.
```
---
title: Julia Add-Chart-Type-or-Topic | Examples | Plotly
name: Add-Chart-Type-or-Topic
permalink: julia/add-chart-type-or-topic/
description: How to make a add-chart-type-or-topic in Julia. Add an additional sentence summarizing chart-type or topic.
layout: base
thumbnail: thumbnail/add-chart-type-or-topic.jpg *MORE INFO ON ADDING THUMBNAILS BELOW
language: julia
page_type: example_index
display_as: **SEE BELOW
order: ***SEE BELOW
---
{% assign examples = site.posts | where:"language","julia" | where:"suite","add-chart-type-or-topic"**** | sort: "order" %}
{% include posts/auto_examples.html examples=examples %}
```
- **`display_as` sets where your tutorial is displayed
- 'basic' = https://plotly.com/julia/#basic-charts
- 'statistical' = https://plotly.com/julia/#statistical-charts
- 'scientific' = https://plotly.com/julia/#scientific-charts
- 'financial' = https://plotly.com/julia/#financial-charts
- 'maps' = https://plotly.com/julia/#maps
- '3d_charts' = https://plotly.com/julia/#3d-charts
- See additional options [HERE](https://github.com/plotly/graphing-library-docs/blob/master/_includes/documentation_eg.html#L1)
- *** `order` defines the order in which the tutorials appear in each section on plot.ly/julia. Please take a look at https://plotly.com/julia/ and order your tutorial next to similar chart types. <b>Note</b> `order` can be a float.
To preview Julia documentation locally, follow the setup steps in the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally), then run:

3. Create an example and save it on https://plotly.com/.
```sh
make fetch_upstream_files
bundle exec jekyll serve --config _config_dev.yml
```

4. Add an HTML file (`yyyy-mm-dd-example-name.html`) for each example. The HTML file should have a header (template below), followed by the Julia code used to create the example.
```
---
name: Basic Bar Chart **
plot_url: https://plotly.com/~PlotBot/39
language: julia
suite: bar
order: 1 **
sitemap: false
arrangement: horizontal
---
# Learn about API authentication here: https://plotly.com/julia/getting-started
# Find your api_key here: https://plotly.com/settings/api
`fetch_upstream_files` clones the latest built Julia content into `_posts/julia/html/`. Without it, the Julia pages will not render locally.

using Plotly
## Pull requests


data = [
[
"x" => ["giraffes", "orangutans", "monkeys"],
"y" => [20, 14, 23],
"type" => "bar"
]
]
response = Plotly.plot(data, ["filename" => "basic-bar", "fileopt" => "overwrite"])
plot_url = response["url"]
```

6. Best Practices:
- <b>Now we have an awesome navigation bar on the left side of our tutorial pages.</b> The navigation bar displays the `name`** in the `order`** so add a `name` for each example and try to make `name`s 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 :) )

8. 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 <b>Amazon Web Services Console</b> select <b>S3 (Scalable Storage in the Cloud)</b> then select <b>plotly-tutorials</b> -> <b>plotly-documentation</b> -> <b>thumbnail</b>
- Now from <b>All Buckets /plotly-tutorials/plotly-documentation/thumbnail</b> select the <b>Actions</b> dropdown and <b>upload</b> your .jpg file

##### In the terminal in the `documentation` repo
9. Commit and Push your tutorial
- `git add` your .html files
- `git commit -m "include a message about the tutorial you're adding"`
- `git push origin master`

10. To proof your work, serve the pages locally by running: `bundle exec jekyll serve --config _config_dev.yml` from the root of the documentation repo.
For more information see these steps: https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md

11. Deploy changes by running `bundle exec rake deploy` from the root of the documentation repo.

##### At https://plotly.com/julia
12. Check your Tutorial!!!! This is a <b>very important</b> step.
<b>PLEASE</b> visit https://plotly.com/julia/your-tutorial and make sure everything looks correct :)

- 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://plotly.com/julia/

Thanks for contributing to our documentation!!
Open a pull request against the `master` branch of [plotly/graphing-library-docs](https://github.com/plotly/graphing-library-docs) for changes to the Julia landing pages, or against [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs) for changes to tutorial content. A Plotly maintainer will review.
Loading
Loading