Skip to content

Commit a4d8b8b

Browse files
committed
Add "dogfood" instructions for previewing the MyST site with jupyter-myst-build-proxy
1 parent 6a23871 commit a4d8b8b

File tree

1 file changed

+44
-1
lines changed

1 file changed

+44
-1
lines changed

for-instructors/dogfooding.md

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,47 @@ Once you've set up GitHub authentication, you can use Git normally.
1919

2020
## Previewing the MyST site
2121

22-
TODO
22+
We have installed
23+
[`jupyter-myst-build-proxy`](https://github.com/ryanlovett/jupyter-myst-build-proxy)
24+
which builds the MyST site on-demand.
25+
26+
To view your built site:
27+
28+
* Copy the URL of your server (e.g. Matt's URL is
29+
`https://hub.cryointhecloud.com/user/mfisher87/lab`)
30+
* Open a new browser tab
31+
* Paste the URL in the URL bar
32+
* Replace `/lab` with `/myst-build/$DIRECTORY_OF_MYST_PROJECT`; for example, Matt's
33+
project is at `~/workshop-open-source-geospatial`, so his URL would be
34+
`https://hub.cryointhecloud.com/user/mfisher87/myst-build/workshop-open-source-geospatial`.
35+
36+
At this point you should see the build progress in your browser. It should only take a
37+
few seconds, and then you'll see your fully-built MyST site!
38+
39+
40+
### Tradeoffs
41+
42+
Unfortunately, this extension uses the `myst build --html` command instead of `myst
43+
start`
44+
([read more here](https://github.com/ryanlovett/jupyter-myst-build-proxy/issues/8)).
45+
As a consequence, builds are not triggered automatically when edits are performed.
46+
47+
Builds are triggered in two ways:
48+
49+
* First build: When the user first accesses the URL corresponding to the MyST project,
50+
and the built site is not found, a build is triggered.
51+
A nice UI shows the user progress in their browser during the build.
52+
* Subsequent builds: The user must append `/?rebuild=1` to the URL to trigger subsequent
53+
builds.
54+
55+
56+
#### Pros
57+
58+
* User doesn't need to run anything in the terminal to build their site
59+
* Handles BASE_URL concerns implicitly
60+
61+
62+
#### Cons
63+
64+
* Not portable to local usage after the workshop
65+
* Builds only occur when manually triggered

0 commit comments

Comments
 (0)