Documentation hosts like Netlify and Read the Docs build a fresh preview of your site for every pull request with a link to preview.
Use the clinder CLI in that build to execute your notebooks on Binder and build the site with MyST to preview yourself.
This repository previews its own docs on Netlify at https://
How it works¶
The docs-binder nox session starts a Binder session with clinder, exports JUPYTER_BASE_URL and JUPYTER_TOKEN, and builds the MyST site with --execute.
MyST picks up those environment variables and runs every code cell on the Binder pod.
Netlify configuration¶
Our netlify.toml configuration has the configuration we use to execute with Binder.
Here’s the full config:
# Build the docs site on Netlify.
# Runs from the repo root so `nox` can find noxfile.py; the `docs` session
# changes into docs/ and builds with mystmd (which brings its own Node).
[build]
publish = "docs/_build/html"
command = "pip install nox && nox -s docs-binder"
# Only build pull request deploy previews and skip builds on `main`
ignore = "[ \"$CONTEXT\" != \"deploy-preview\" ]"
The ignore line restricts builds to PR deploy previews, since the production site is published elsewhere.
Other hosts¶
The same idea works anywhere you control the build command (Read the Docs, GitLab Pages, etc.): install clinder, start a session, and build your docs with the two JUPYTER_* variables in the environment.