From 3f0a0e00d4f269aaf1f8e64d1b86a97936b96355 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 18:52:37 +0000 Subject: [PATCH 1/3] Add "dogfood" instructions for previewing the MyST site with jupyter-myst-build-proxy --- for-instructors/dogfooding.md | 45 ++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/for-instructors/dogfooding.md b/for-instructors/dogfooding.md index 788764e..a0de3eb 100644 --- a/for-instructors/dogfooding.md +++ b/for-instructors/dogfooding.md @@ -19,4 +19,47 @@ Once you've set up GitHub authentication, you can use Git normally. ## Previewing the MyST site -TODO +We have installed +[`jupyter-myst-build-proxy`](https://github.com/ryanlovett/jupyter-myst-build-proxy) +which builds the MyST site on-demand. + +To view your built site: + +* Copy the URL of your server (e.g. Matt's URL is + `https://hub.cryointhecloud.com/user/mfisher87/lab`) +* Open a new browser tab +* Paste the URL in the URL bar +* Replace `/lab` with `/myst-build/$DIRECTORY_OF_MYST_PROJECT`; for example, Matt's + project is at `~/workshop-open-source-geospatial`, so his URL would be + `https://hub.cryointhecloud.com/user/mfisher87/myst-build/workshop-open-source-geospatial`. + +At this point you should see the build progress in your browser. It should only take a +few seconds, and then you'll see your fully-built MyST site! + + +### Tradeoffs + +Unfortunately, this extension uses the `myst build --html` command instead of `myst +start` +([read more here](https://github.com/ryanlovett/jupyter-myst-build-proxy/issues/8)). +As a consequence, builds are not triggered automatically when edits are performed. + +Builds are triggered in two ways: + +* First build: When the user first accesses the URL corresponding to the MyST project, + and the built site is not found, a build is triggered. + A nice UI shows the user progress in their browser during the build. +* Subsequent builds: The user must append `/?rebuild=1` to the URL to trigger subsequent + builds. + + +#### Pros + +* User doesn't need to run anything in the terminal to build their site +* Handles BASE_URL concerns implicitly + + +#### Cons + +* Not portable to local usage after the workshop +* Builds only occur when manually triggered From 2865bb4d90d8e52e7adad48efff68215286afbfe Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 22:09:20 +0000 Subject: [PATCH 2/3] Adjust tradeoff text to reflect this as the only reasonable option --- for-instructors/dogfooding.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/for-instructors/dogfooding.md b/for-instructors/dogfooding.md index a0de3eb..f9a8260 100644 --- a/for-instructors/dogfooding.md +++ b/for-instructors/dogfooding.md @@ -39,7 +39,7 @@ few seconds, and then you'll see your fully-built MyST site! ### Tradeoffs -Unfortunately, this extension uses the `myst build --html` command instead of `myst +This extension uses the `myst build --html` command instead of `myst start` ([read more here](https://github.com/ryanlovett/jupyter-myst-build-proxy/issues/8)). As a consequence, builds are not triggered automatically when edits are performed. @@ -52,6 +52,9 @@ Builds are triggered in two ways: * Subsequent builds: The user must append `/?rebuild=1` to the URL to trigger subsequent builds. +There is currently no known way to use the MyST preview server `myst start` in a +JupyterLab environment. See https://github.com/jupyter-book/mystmd/issues/302 + #### Pros From 7f4f813794d533e572ef57515ce3dd49bb4493d6 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 22:57:14 +0000 Subject: [PATCH 3/3] Extract MyST build instructions to reference --- for-instructors/dogfooding.md | 21 +-------------------- reference/04-using-myst.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 20 deletions(-) create mode 100644 reference/04-using-myst.md diff --git a/for-instructors/dogfooding.md b/for-instructors/dogfooding.md index f9a8260..b386ad4 100644 --- a/for-instructors/dogfooding.md +++ b/for-instructors/dogfooding.md @@ -23,18 +23,7 @@ We have installed [`jupyter-myst-build-proxy`](https://github.com/ryanlovett/jupyter-myst-build-proxy) which builds the MyST site on-demand. -To view your built site: - -* Copy the URL of your server (e.g. Matt's URL is - `https://hub.cryointhecloud.com/user/mfisher87/lab`) -* Open a new browser tab -* Paste the URL in the URL bar -* Replace `/lab` with `/myst-build/$DIRECTORY_OF_MYST_PROJECT`; for example, Matt's - project is at `~/workshop-open-source-geospatial`, so his URL would be - `https://hub.cryointhecloud.com/user/mfisher87/myst-build/workshop-open-source-geospatial`. - -At this point you should see the build progress in your browser. It should only take a -few seconds, and then you'll see your fully-built MyST site! +See [](../reference/04-using-myst.md) for instructions. ### Tradeoffs @@ -44,14 +33,6 @@ start` ([read more here](https://github.com/ryanlovett/jupyter-myst-build-proxy/issues/8)). As a consequence, builds are not triggered automatically when edits are performed. -Builds are triggered in two ways: - -* First build: When the user first accesses the URL corresponding to the MyST project, - and the built site is not found, a build is triggered. - A nice UI shows the user progress in their browser during the build. -* Subsequent builds: The user must append `/?rebuild=1` to the URL to trigger subsequent - builds. - There is currently no known way to use the MyST preview server `myst start` in a JupyterLab environment. See https://github.com/jupyter-book/mystmd/issues/302 diff --git a/reference/04-using-myst.md b/reference/04-using-myst.md new file mode 100644 index 0000000..2933788 --- /dev/null +++ b/reference/04-using-myst.md @@ -0,0 +1,26 @@ +# 📝 Using MyST + +## Previewing your MyST site + +### First time + +To view your built site: + +* Copy the URL of your server (e.g. Matt's URL is + `https://hub.cryointhecloud.com/user/mfisher87/lab`) +* Open a new browser tab +* Paste the URL in the URL bar +* Replace `/lab` with `/myst-build/$DIRECTORY_OF_MYST_PROJECT`; for example, Matt's + project is at `~/workshop-open-source-geospatial`, so his URL would be + `https://hub.cryointhecloud.com/user/mfisher87/myst-build/workshop-open-source-geospatial`. + +At this point you should see the build progress in your browser. +It should only take a few seconds, and then you'll see your fully-built MyST site! + + +### Subsequent builds + +Your site will not automatically rebuild when you make changes! +This functionality will be available in the future. + +Append `/?rebuild=1` to the URL to trigger a rebuild.