Support running MyST previews / running a myst server on JupyterHub

[fperez]

When a user wants to author MyST sites in a JupyterHub, they need a way to preview the outputs via a MyST server. Currently, this doesn't work because of the way that the BASE_URL writing works.

Next actions

• [ ] Decide if this is something we can fix directly, or if it requires a more deep improvement in our web server tech via https://github.com/jupyter-book/myst-theme/issues/558

Implementation ideas

Ideally, if the environment variable ${JUPYTERHUB_SERVICE_PREFIX} is set, then the myst server would respond with the proper handling equivalent to the sphinx config example above. And in a future setting where static HTML builds (à la sphix/jbook) are possible, then it would also recognize this.

If doing it automatically isn't desirable, then at least having the option to manually set the base URL like sphinx supports would work.

• Quarto has some logic for detecting whether it's run on a JupyterHub and updating the start logic accordingly: https://github.com/quarto-dev/quarto-cli/blob/68ea0b28cb03492628836784adf04d7da43a484f/src/core/previewurl.ts#L76-L85

Challenge with our static web outputs framework

The challenge with this fix is that currently our static HTML builds are made with some hacks that are kind-of brittle, and that lead to problems like these. This means we have a choice between:

• A one-off fix to make this kind of thing work.
• A deeper fix to the static HTML builds that will make issues like this less common in general (I think this one is being discussed in https://github.com/jupyter-book/myst-theme/issues/558).

So we need to decide which of these we want to pursue to tackle this.

Jupyter Book 1 example with python -m http.server

While it's not super convenient, it is possible to build jupyter-books to be viewed in a hosted JuptyerHub instance thanks to the URL proxy it uses. In that case, one has to invoke sphinx manually in order to force a special html_baseurl, via:

jupyter-book config sphinx .
sphinx-build  . _build/html -D html_baseurl=${JUPYTERHUB_SERVICE_PREFIX}/proxy/absolute/8000

But once this is done, one can simply run in the _build/html directory the command:

python -m http.server

and access the URL https://your-jupyterhub.org/user-redirect/proxy/8000/index.html.

When I try to follow the equivalent process with myst, by running the myst server and trying to access .../proxy/3000/index.html, I get redirected to a page that looks like this: