docs: Update build docs and clarify instructions by camdecoster · Pull Request #438 · plotly/graphing-library-docs

camdecoster · 2026-05-18T19:07:07Z

Description

Update the build docs to clarify how to get local dev set up and how to deploy updates to the docs.

red-patience · 2026-05-19T14:30:28Z

 ![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)

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


I think this goes without saying! 😅

red-patience · 2026-05-19T14:32:22Z

@@ -34,13 +34,13 @@ The easiest way to do this is to follow the `Edit this page on GitHub` link at t

 ![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)


Might be worth refreshing this screenshot. The site looks outdated and it looks like the button itself has changed

red-patience · 2026-05-19T14:48:03Z

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


We use indexes in ddk-dash-docs (see https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/i/index-indexes-indices)

red-patience · 2026-05-19T14:49:27Z

+
+You can browse the indices 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. The `schema` index should be updated when a new plotly.js version is released.


Should makes your intent unclear here. Are you asking users to update it, or are you saying it's an automated update?

I'll reword it.

red-patience · 2026-05-19T14:51:13Z

-When you run a `$ jekyll` you need to update any scss file as jekyll will automatically replace the styles.css file. e.g.: if you modify any scss file and save it, it will overwrite the file jekyll has produced.
+It's a bit of a hassle to make concurrent updates to markup and scss. Any time you update an html/js file you'll have to run `bundle exec jekyll build` (or run `bundle exec jekyll serve` with Jekyll watching for changes). Jekyll's watch mode can be slow on this repo because of its size; building on demand is sometimes preferable.
+
+When you run `bundle exec jekyll …`, Jekyll will regenerate `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.


Suggested change

When you run `bundle exec jekyll …`, Jekyll will regenerate `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.

When you run `bundle exec jekyll …`, Jekyll regenerates `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.

red-patience · 2026-05-19T15:09:56Z

-Generally it's best to work with two instances of terminal, one to use for anything related to `$ jekyll` and then another to keep the `$ gulp` task running.
-
-1. run `$ jekyll serve --config _config_dev.yml` to create a local server @ http://localhost:4000 that browsersync leverages (see gulpfile.js to adjust as needed)
+Once the repo has been cloned successfully (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.


Suggested change

Once the repo has been cloned successfully (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.

Once you have successfully cloned the repo (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.

Active voice is better for instructions

red-patience · 2026-05-19T15:13:08Z

+
+**When to update:** Run the appropriate `update_*_search` target whenever a new tutorial is added to the corresponding `_posts/` directory. The `schema` index should be updated 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.


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

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

red-patience

Great cleanup!

docs: Update build docs and clarify instructions

6341ac1

red-patience reviewed May 19, 2026

View reviewed changes

red-patience approved these changes May 19, 2026

View reviewed changes

camdecoster added 2 commits May 19, 2026 15:04

Update image in README.md

68a7bd1

Address PR feedback

436808c

camdecoster merged commit 717a1a6 into master May 19, 2026
1 check passed

		@@ -34,13 +34,13 @@ The easiest way to do this is to follow the `Edit this page on GitHub` link at t

		![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)


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

		## Search indices


		You can browse the indices 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. The `schema` index should be updated when a new plotly.js version is released.

	When you run `bundle exec jekyll …`, Jekyll will regenerate `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.
	When you run `bundle exec jekyll …`, Jekyll regenerates `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.

	Once the repo has been cloned successfully (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.
	Once you have successfully cloned the repo (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.


		When to update: Run the appropriate `update_*_search` target whenever a new tutorial is added to the corresponding `_posts/` directory. The `schema` index should be updated 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.

Uh oh!

Conversation

camdecoster commented May 18, 2026

Description

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

red-patience left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants