Add dogfooding instructions for MyST previews with jupyter-myst-build-proxy (#23)

Author: mfisher87

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

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.