Documentation conversion into Mkdocs #7609

daexs · 2025-10-28T16:30:08Z

Converted the plotly.js documentation build into Mkdocs

Create a Mkdocs build for the plotly.js docs and reference pages, including styling.
Minor modification to ‎src/traces/image/attributes.js for proper Markdown rendering on plotly.py docs' function docstrings.
Generates HTML snippets which are then inserted into the Markdown files for examples and references.
Uses javascript and hljs to apply tags to code block text which code-highlight.css applies syntax highlighting. This is done because the markdown files are HTML snippets.
Home/Landing page is plotly/plotly.js/README.md and index pages are placed in each individual category of examples under Overview.

…ocs-conversion

- Import Jekyll material from graphic-library-docs repository. - Remove (most) mentions of languages other than Python and JavaScript. - Add Makefile to re-run commands.

… into mkdocs-conversion

…nto mkdocs-conversion

…the html snippets for each file under 'docs/tmp/'

…ipt docs.

…om the 'mkdocs.yml' file.

…tyling

- Add `./Makefile` with commands to rebuild documentation using the commands shown below. (We'll tidy this up in the final step.) - `make examples` - `make reference` - `make build` - Move scripts from `./docs/bin` to `./bin` and adjust paths in scripts as needed to pick up the right files and to build into `./tmp`. - Modify `./mkdocs.yml` to build from `./tmp`. - Modify `./.gitignore` to ignore `./tmp`. Note that this is only a step toward the final cleaned-up version: the next step is to move `./docs/_posts` into the root directory, then remove `./docs` entirely and build the site into `./docs` rather than into `./doc`.

refactor: move documentation generation into the root directory

- and remove last vestiges of Jekyll

…into mkdocs-conversion

…ow on banners and header

LiamConnors · 2025-11-06T15:01:51Z

CONTRIBUTING-DOCS.md

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


Is this accurate? I don't see that directory

LiamConnors · 2025-11-06T15:02:13Z

CONTRIBUTING-DOCS.md

+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 https://github.com/plotly/graphing-library-docs. 
+
+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](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)
+
+**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.


This readme should be updated to have the new steps

LiamConnors · 2025-11-06T15:10:01Z

docs/404.html

@@ -0,0 +1,4518 @@
+


Is page used to generate what's in content and then that's used for what's in docs?
Is there a reason why we'd need to commit this generated content?

Yes, docs used to contain different content (unsure what exactly but it was related to the old build) and is now used to hold the site contents when you run mkdocs build. There is no reason to keep the generated content, it just hasn't been removed yet after the mkdocs changes, will remove it now!

LiamConnors · 2025-11-06T15:13:33Z

test/plot-schema.json

@@ -3452,7 +3444,7 @@
     "valType": "number"
    },
    "maxheight": {
-     "description": "Sets the max height (in px) of the legend, or max height ratio (reference height * ratio) if less than or equal to 1. Default value is: 0.5 for horizontal legends; 1 for vertical legends. The minimum allowed height is 30px. For a ratio of 0.5, the legend will take up to 50% of the reference height before displaying a scrollbar. The reference height is the full layout height with the following exception: vertically oriented legends with a `yref` of `\"paper\", located to the side of the plot. In this case, the reference height is the plot height.",
+     "description": "Sets the max height (in px) of the legend, or max height ratio (reference height * ratio) if less than one. Default value is: 0.5 for horizontal legends; 1 for vertical legends. The minimum allowed height is 30px. For a ratio of 0.5, the legend will take up to 50% of the reference height before displaying a scrollbar. The reference height is the full layout height except for vertically oriented legends with a `yref` of `\"paper\"`, where the reference height is the plot height.",


Should these changes be here? I see some attributes are removed.

@LiamConnors This branch probably needs to be updated with the latest changes from master

LiamConnors · 2025-11-06T15:23:33Z

pyproject.toml

+[project]
+name = "plotly.js"
+description = "Plotly JavaScript charting library"
+version = "3.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "markdown",
+    "python-frontmatter",
+    "ruff"
+]
+
+[project.optional-dependencies]
+dev_build = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav",
+    "markdown-include",
+    "mkdocs-macros-plugin",
+    "mkdocs-redirects",
+]


I think the breakdown of dependencies here suggests there are dependencies for Plotly.js. But is this pyproject.toml just for the docs?

I agree with Liam that pyproject.toml is a confusing file to include here since Plotly.js is not a Python project. Could the dependencies be tracked in a requirements.txt file instead, inside a docs/ subdirectory maybe? We can discuss.

LiamConnors · 2025-11-06T15:27:37Z

Makefile

+# Manage plotly.js documentation.
+
+RUN = uv run
+SCHEMA_SRC = test/plot-schema.json
+HANDWRITTEN = content
+TMP = tmp
+
+EXAMPLES_DIR = ${HANDWRITTEN}/plotly_js
+EXAMPLES_IN := $(shell find "${EXAMPLES_DIR}" -name '*.html')
+EXAMPLES_TMP = ${TMP}/javascript
+EXAMPLES_OUT = ${EXAMPLES_TMP}/axes/index.html # could be any of the generated files
+
+REFERENCE_DIR = ${HANDWRITTEN}/reference_pages/javascript/
+REFERENCE_IN := $(wildcard ${REFERENCE_DIR}/*.html)
+REFERENCE_TMP = ${TMP}/reference
+REFERENCE_OUT = ${REFERENCE_TMP}/bar/index.html # could be any of the generated files
+
+DOCS_DIR=docs
+DOCS_OUT=${DOCS_DIR}/sitemap.xml
+
+## commands: show available commands
+commands:
+	@grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':'
+
+## docs: rebuild full documentation in `./docs`
+.PHONY: docs
+docs: ${DOCS_OUT}
+
+${DOCS_OUT}: ${EXAMPLES_OUT} ${REFERENCE_OUT}


Could we add to the docs contributing guide on how to build the docs, and maybe a GitHub action that runs the required steps to test generating the output.

mkdocs.yml

emilykl · 2025-11-06T16:41:00Z

General comment on file organization: I'd like to minimize the number of files added at the top level of this repo. Ideally anything related to the docs should be contained inside a docs/ subdirectory, except for perhaps a single .md file explaining the process for building the docs.

emilykl · 2025-11-06T16:49:59Z

.gitignore

+
+tmp
+
+docs


A directory being added by this PR should not be in the .gitignore!

I removed the directory just now since it was generated content and there is no need to commit it into the repo. I kept the .gitignore as is because mkdocs will generate its site there if you run mkdocs build.

gvwilson and others added 30 commits August 14, 2025 11:11

regenerating test/plot-schema.json

68fee45

Modified URI link in description

c685e71

Merge branch 'master' of https://github.com/plotly/plotly.js into mkd…

2aebe7a

…ocs-conversion

feat: building JavaScript docs locally

57e487a

- Import Jekyll material from graphic-library-docs repository. - Remove (most) mentions of languages other than Python and JavaScript. - Add Makefile to re-run commands.

Merge branch 'master' into building-docs

3e015f5

escaping string

6375ea9

Merge branch 'mkdocs-conversion' of https://github.com/plotly/plotly.js…

d3e57c5

… into mkdocs-conversion

feat: building JavaScript pages with Python instead of Jekyll

0a5a2c3

updating Makefile

3a48587

Merge branch 'building-docs' of https://github.com/plotly/plotly.js i…

91c8be4

…nto mkdocs-conversion

Configured mkdocs and have it auto-generate markdown files including …

24ba085

…the html snippets for each file under 'docs/tmp/'

Modified the navigation bar to be consistent with plotly.py docs

b8bb388

Cleaned up code and added comments for clarity

c899732

Reorganized the navigation bar to match the current published JavaScr…

42534be

…ipt docs.

Modified 'docs/bin/example_pages.py' to read the plotly.js version fr…

096f17e

…om the 'mkdocs.yml' file.

Removed column div tags when generating html for examples in 'docs/tmp'

6316104

Added plotly studio image to nav bar on the left and applied plotly s…

50e0d17

…tyling

Merge pull request #7 from daexs/clean-up-mkdocs-build

0a4f3b5

refactor: move documentation generation into the root directory

feat: move docs/_posts pages into content directory

ff846b4

- and remove last vestiges of Jekyll

removing Angular.js instructions in BUILDING.md (outdated)

e3f5a0f

Tidying up README.md

ab21dd0

adding 'docs' with generated documentation

040d94e

removing mentions of Plotly.R

2ca8ef7

a bit of documentation and reformatting

c2ea8f7

feat: remove YYYY-DD-MM prefixes from handwritten page names

5d31640

Added footer

16d4a7d

Merge branch 'mkdocs-conversion' of https://github.com/daexs/plotly.js …

f91d4b6

…into mkdocs-conversion

Changed javascript version for codepen and fixed typo in footer link

becb4a3

Added syntax highlighting to the JavaScript code blocks

6b6173c

daexs added 12 commits October 16, 2025 11:33

Added overview page to API Reference section in nav bar.

9f2fd73

Added plotly fundamentals index page

d7a2f23

Add index pages to each category in the nav bar

fedda96

Fix internal links

ea56157

Add redirects, styled hamburger menu, and redisplay external link arr…

7508c5e

…ow on banners and header

Pushed all markdown files under 'examples/' up a level for SEO

7730e74

Added styling for footer text when page is in dark mode.

d2088ba

Added syntax highlighting that changes in dark mode.

e596f43

Added an 'edit this page' button

bb04038

Fixed styling of icon in edit button

8e4d970

Update .gitignore file and plotly ad in nav bar

22ee456

Merge remote-tracking branch 'upstream/live-docs' into mkdocs-conversion

7f6ac5d

daexs requested a review from LiamConnors October 28, 2025 19:03

LiamConnors reviewed Nov 6, 2025

View reviewed changes

LiamConnors requested review from camdecoster and emilykl November 6, 2025 15:15

LiamConnors reviewed Nov 6, 2025

View reviewed changes

mkdocs.yml Outdated Show resolved Hide resolved

Changed section in pyproject.toml for docs dependencies into 'docs'.

5c42341

emilykl reviewed Nov 6, 2025

View reviewed changes

Update mkdocs.yml to get rid of the literate-nav plugin

e758a9e

daexs self-assigned this Nov 6, 2025

daexs added feature something new P1 needed for current cycle labels Nov 6, 2025

Removed the 'docs' folder containing the mkdocs build

5e7d332

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

Uh oh!

Documentation conversion into Mkdocs #7609

Are you sure you want to change the base?

Documentation conversion into Mkdocs #7609

Conversation

daexs commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Uh oh!

emilykl commented Nov 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daexs Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

daexs commented Oct 28, 2025 •

edited

Loading

daexs Nov 6, 2025 •

edited

Loading