diff --git a/for-instructors/dogfooding.md b/for-instructors/dogfooding.md index 788764e..b386ad4 100644 --- a/for-instructors/dogfooding.md +++ b/for-instructors/dogfooding.md @@ -19,4 +19,31 @@ 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. + +See [](../reference/04-using-myst.md) for instructions. + + +### Tradeoffs + +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. + +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 + +* 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 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.