From b330629efd8b04e4ad33b0280536e7c5a1903193 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 22:52:44 +0000 Subject: [PATCH 01/15] Init module 5 draft (WIP) --- modules/05-sharing-and-publishing/index.md | 46 ++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index b86b25f..09d450b 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -32,3 +32,49 @@ authors: webkitallowfullscreen="true"> ::: + + +## Technical publishing with MyST + +MyST (Markedly Structured Text) is both: + +* A language, which extends Markdown, for authoring technical documents, including executable code cells, **and** +* A software tool for rendering technical documents from MyST source + + +## Using MyST in JupyterLab + +This JupyterLab instance has MyST installed, plus a special configuration for building +and exposing a MyST site at a special URL. + +To preview a MyST site, first... + +::::::{info} Using MyST on your local machine +:class: dropdown + +The special configuration for building and hosting our MyST site is not necessary on a +local computer. +We even have some special features that we can't use in the JupyterLab environment, +for example a live-updating preview server: + +```bash +myst start +``` + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...when the preview server successfully starts, the following message is printed: + +``` +🔌 Server started on port 3000! 🥳 🎉 + + + 👉 http://localhost:3000 👈 +``` + +At this point, you can visit the printed URL to preview your site. +The preview will automatically update any time you change a file. +::: +:::::: From 6cc96127f83355e2c540d3d64ad133edacac809e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 23:27:59 +0000 Subject: [PATCH 02/15] Flesh out some content on building a MyST website Both on JupyterLab and locally --- modules/05-sharing-and-publishing/index.md | 50 ++++++++++++++++++---- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 09d450b..05336c6 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -38,22 +38,40 @@ authors: MyST (Markedly Structured Text) is both: -* A language, which extends Markdown, for authoring technical documents, including executable code cells, **and** -* A software tool for rendering technical documents from MyST source +* A language, which extends Markdown, for authoring technical documents, including + executable code cells, **and** +* A software tool for executing and rendering technical documents from MyST source to + multiple output formats including websites, PDFs, $ \LaTeX $, Typst, MS Word, JATS, + and `CITATION.cff`. -## Using MyST in JupyterLab +## Building a website + +### Building a MyST site in JupyterLab This JupyterLab instance has MyST installed, plus a special configuration for building and exposing a MyST site at a special URL. -To preview a MyST site, first... +To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...when you open the URL specified in the instructions above, a loading screen is +displayed. + +After a few seconds, the build will complete and you can see your fully-built site! +::: -::::::{info} Using MyST on your local machine +::::::{note} Building a MyST site on your local machine :class: dropdown -The special configuration for building and hosting our MyST site is not necessary on a -local computer. +It's important to us that you can take these skills home with you! +Some things will be slightly different outside of JupyterLab. + +The special configuration for building and hosting our MyST site in JupyterLab is not +necessary on a local computer. We even have some special features that we can't use in the JupyterLab environment, for example a live-updating preview server: @@ -70,7 +88,6 @@ myst start ``` 🔌 Server started on port 3000! 🥳 🎉 - 👉 http://localhost:3000 👈 ``` @@ -78,3 +95,20 @@ At this point, you can visit the printed URL to preview your site. The preview will automatically update any time you change a file. ::: :::::: + + +### Hosting your website for free + +#### GitHub Pages + +TODO + + +#### ReadTheDocs + +TODO + + +## Building a paper + +TODO From e072b45b8dd534125a940dcdb6419d0501e141b0 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 15:31:12 -0700 Subject: [PATCH 03/15] Add instructions to register access to more repos from CryoCloud --- reference/03-gh-auth.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/reference/03-gh-auth.md b/reference/03-gh-auth.md index 7211a1d..22bd9e2 100644 --- a/reference/03-gh-auth.md +++ b/reference/03-gh-auth.md @@ -31,3 +31,12 @@ follow the instructions within.** After you've completed first-time setup, run the code cell at the end of the Notebook and carefully follow the instructions output by this cell. + + +## Granting permission for pushing to additional repository + +If you only granted access to one repository (recommended), you may want to add more +later. + +You can update the list of repositories you want to grant access to by visiting the +[configuration page for the CryoCloud GitHub application](https://github.com/apps/cryocloud-github-access). From e067ad61100c290033b0b836dfca9d3a6998beb8 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 16:14:07 -0700 Subject: [PATCH 04/15] Display email link and add social links for authors --- modules/05-sharing-and-publishing/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 05336c6..819042f 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -4,16 +4,22 @@ authors: affiliations: - "University of California, Berkeley" - "Schmidt Center for Data Science and Environment" + equal_contributor: true email: "fernando.perez@berkeley.edu" orcid: "0000-0002-1725-9815" github: "fperez" + corresponding: true - name: "Matt Fisher" affiliations: - "University of California, Berkeley" - "Schmidt Center for Data Science and Environment" + equal_contributor: true email: "matt.fisher@berkeley.edu" orcid: "0000-0003-3260-5445" github: "mfisher87" + bluesky: "mfisher87.bsky.social" + linkedin: "https://www.linkedin.com/in/mattfisher8" + corresponding: true --- # 📢 5 - Sharing & Publishing Your Work From 24002657fe0c0f8f16a0084f293dbcfc58c3fc0d Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 16:29:14 -0700 Subject: [PATCH 05/15] Rework the "What is MyST" and "Building a website with MyST" sections --- modules/05-sharing-and-publishing/index.md | 105 +++++++++++++++------ 1 file changed, 75 insertions(+), 30 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 819042f..e7ac582 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -40,62 +40,107 @@ authors: ::: -## Technical publishing with MyST +## What is MyST? -MyST (Markedly Structured Text) is both: +MyST (Markedly Structured Text) is both a language and a software tool. -* A language, which extends Markdown, for authoring technical documents, including - executable code cells, **and** -* A software tool for executing and rendering technical documents from MyST source to - multiple output formats including websites, PDFs, $ \LaTeX $, Typst, MS Word, JATS, - and `CITATION.cff`. +### MyST, the language -## Building a website +MyST, as a language, extends Markdown. -### Building a MyST site in JupyterLab +It adds new syntax, including +["roles" and "directives"](https://mystmd.org/guide/quickstart-myst-markdown#directives-and-roles) +that enable advanced functionality like +[executable code cells](https://mystmd.org/guide/notebooks-with-markdown#code-cell), +[callouts](https://mystmd.org/guide/admonitions) (also known as admonitions), +and [glossaries](https://mystmd.org/guide/glossaries-and-terms), and more. +There is also dedicated syntax for +[citations](https://mystmd.org/guide/citations#markdown-citations), +[math](https://mystmd.org/guide/math), +and more. -This JupyterLab instance has MyST installed, plus a special configuration for building -and exposing a MyST site at a special URL. +Directives are like functions that can receive Markdown content, for example an +callout's text. Roles are just like directives, except they are _inline_ with other +Markdown text. -To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). -:::{important} 👀 You should notice... -:class: simple +#### Example `{glossary}` directive and `{term}` role + +```{myst} +:::{glossary} +Term +: A word or phrase which can be defined in a **glossary** directive. +Directives can include **_rich_** Markdown content. +::: + +{term}`Term` roles create inline references, within your Markdown text, to glossary definitions. +Try hovering over the word "Term" to see a definition. +``` + +:::{tip} 💪 Mini-exercise :icon: false -...when you open the URL specified in the instructions above, a loading screen is -displayed. +Try changing the code for the directive and role in the example above and immediately +observe the results. +::: -After a few seconds, the build will complete and you can see your fully-built site! + +### MySTMD, the software + +[MySTMD](https://mystmd.org/) is a software tool for executing and rendering technical +documents from source in MyST or Notebook input formats to multiple output formats +including websites, PDFs, $ \LaTeX $, Typst, MS Word, JATS, and `CITATION.cff`. + +MySTMD is the software that created this website from its +[source code](https://github.com/geojupyter/workshop-open-source-geospatial) (written in +MyST and Jupyter Notebook format). + + +## Building a website with MyST + +### The normal way + +:::{important} +Because we're working in CryoCloud for this workshop, this section is provided for +informational purposes. +We'll be following the instructions below for using MyST in JupyterLab. ::: -::::::{note} Building a MyST site on your local machine -:class: dropdown +With MySTMD [installed](https://mystmd.org/guide/installing), you can build a MyST +website from source with one command: -It's important to us that you can take these skills home with you! -Some things will be slightly different outside of JupyterLab. +```bash +myst build --html +``` -The special configuration for building and hosting our MyST site in JupyterLab is not -necessary on a local computer. -We even have some special features that we can't use in the JupyterLab environment, -for example a live-updating preview server: +During development, you can also use MyST's convenient preview server to automatically +rebuild your site any time you change its content: ```bash myst start ``` + +### In JupyterLab + +As workshop participants, you have access to CryoCloud, which provides a JupyterLab +instance with MyST pre-installed. +CryoCloud also comes with a special configuration for building a MyST site without the +use of the terminal. + +To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). + :::{important} 👀 You should notice... :class: simple :icon: false -...when the preview server successfully starts, the following message is printed: +...when you open the URL specified in the instructions above, a loading screen is +displayed. -``` -🔌 Server started on port 3000! 🥳 🎉 +After a few seconds, the build will complete and you can see your fully-built site! +::: - 👉 http://localhost:3000 👈 -``` At this point, you can visit the printed URL to preview your site. The preview will automatically update any time you change a file. From 34f0973db151d8c285143f89de2c925e6c7a6a63 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 16:29:41 -0700 Subject: [PATCH 06/15] Restructure remaining content TODOs with exercises --- modules/05-sharing-and-publishing/index.md | 41 +++++++++++++++++----- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index e7ac582..8ff30fc 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -142,24 +142,49 @@ After a few seconds, the build will complete and you can see your fully-built si ::: -At this point, you can visit the printed URL to preview your site. -The preview will automatically update any time you change a file. -::: -:::::: +### 💪 Exercise A: Build _this_ MyST website in JupyterLab + +TODO + + + +### 💪 Exercise B: Build a MyST website _from scratch_ in JupyterLab + +TODO + + +## Building a PDF with MyST + +TODO -### Hosting your website for free +### 💪 Exercise C: Render a PDF from the same source as your website + +TODO + + +## Hosting your website for free + +### GitHub Pages + +TODO + + +### ReadTheDocs + +TODO + -#### GitHub Pages +### 💪 Exercise D: Publish your paper and website to GitHub TODO -#### ReadTheDocs +## Getting a DOI TODO -## Building a paper +### 💪 Exercise E: Get a DOI for your published content on GitHub TODO From 29485f5dbcd361c53159a925bfbfb518594cc0fd Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 16:34:47 -0700 Subject: [PATCH 07/15] Categorize as tutorial --- modules/05-sharing-and-publishing/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 8ff30fc..b7f9751 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -1,4 +1,5 @@ --- +subject: "Tutorial" authors: - name: "Fernando Perez" affiliations: From c63b42d7b62d36d7500f2da63255ce075b4364a4 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 16:47:22 -0700 Subject: [PATCH 08/15] Add "Where we are going" callout --- modules/05-sharing-and-publishing/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index b7f9751..37d7376 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -41,6 +41,15 @@ authors: ::: +:::{tip} 🧭 Where we are going +:icon: false + +In this tutorial we will build and publish a website and PDF paper from scratch. +We'll publish the website and PDF for free on GitHub, and enable automatic generation of +DOIs for our published product. +::: + + ## What is MyST? MyST (Markedly Structured Text) is both a language and a software tool. From 3a9f607279d8801febcddfceadb26697e5af0950 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 17:07:26 -0700 Subject: [PATCH 09/15] Fill out exercise A --- modules/05-sharing-and-publishing/index.md | 44 +++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 37d7376..1f7ab2d 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -154,8 +154,50 @@ After a few seconds, the build will complete and you can see your fully-built si ### 💪 Exercise A: Build _this_ MyST website in JupyterLab -TODO +_TODO_: Will the participants already have the workshop cloned? Or does that need to be +a step here? + + +#### Navigate to the correct directory in the file browser + +On the left panel, ensure the JupyterLab file browser tab (📁 icon) is selected. + +Double click the folder in the file browser named `workshop-open-source-geospatial`. + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...a listing of around a dozen files and directories, including Markdown files and a +file named `myst.yml`. +::: + + +#### Build the MyST website + +Location the MyST project configuration file, `myst.yml`, in the file browser. + +Right click this file and select the top option from the menu: "Build MyST project". + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...a new browser tab opens with a loading spinner and the title "Building MyST Site". + +After around 5 seconds, the build will complete and the website content will display +automatically. + +At the top-left is the website title: "Open Source Geospatial Workflows in the Cloud". +At the top-right is a button with the text "Rebuild". +::: + + +#### 🧠 What do we know now? +* A MyST project is configured by a `myst.yml` file +* In JupyterLab, we can right-click `myst.yml` to trigger a build (requires + [jupyter-myst-build-proxy](https://github.com/ryanlovett/jupyter-myst-build-proxy/)) ### 💪 Exercise B: Build a MyST website _from scratch_ in JupyterLab From d02a9744bf41f02a14bae855fd242030ef354f50 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 17:09:07 -0700 Subject: [PATCH 10/15] Add consistent structure to all exercises --- modules/05-sharing-and-publishing/index.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 1f7ab2d..c8578da 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -205,6 +205,11 @@ At the top-right is a button with the text "Rebuild". TODO +#### 🧠 What do we know now? + +TODO + + ## Building a PDF with MyST TODO @@ -214,6 +219,10 @@ TODO TODO +#### 🧠 What do we know now? + +TODO + ## Hosting your website for free @@ -231,6 +240,10 @@ TODO TODO +#### 🧠 What do we know now? + +TODO + ## Getting a DOI @@ -240,3 +253,7 @@ TODO ### 💪 Exercise E: Get a DOI for your published content on GitHub TODO + +#### 🧠 What do we know now? + +TODO From 9437caf712c0d13106b7e27469a8d79cba34811d Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 19 Nov 2025 18:39:55 -0700 Subject: [PATCH 11/15] Populate exercise B content --- .../github-repo-name.jpg | Bin 0 -> 20518 bytes modules/05-sharing-and-publishing/index.md | 235 +++++++++++++++++- 2 files changed, 232 insertions(+), 3 deletions(-) create mode 100644 modules/05-sharing-and-publishing/github-repo-name.jpg diff --git a/modules/05-sharing-and-publishing/github-repo-name.jpg b/modules/05-sharing-and-publishing/github-repo-name.jpg new file mode 100644 index 0000000000000000000000000000000000000000..4fe8ba69d17abefe778069615f386dfbe73931ea GIT binary patch literal 20518 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 +``` + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +This command produces the following output: + +``` +Cloning into 'myst-exercise'... +warning: You appear to have cloned an empty repository. +``` +::: + + +#### Initialize your MyST project + +First, change directory into your empty repository: + +```bash +cd myst-exercise +``` + +Next, initialize your MyST project with configuration needed to generate a website: + +```bash +myst init --project --site +``` + + +#### Create some content + +Create a new file `index.md` using the JupyterLab interface: + +* Right-click in the empty space in the file browser. +* Select "New file". +* Input the name `index.md`. + +Enter the following content in the file (click the copy button at the top-right of this +code block): + +```{code} markdown +:filename: index.md + +Hello, world! + +$$ +1 + 1 = 2 +$$ +``` + +The `$$` symbols delimit a math equation, and you can write any $ \LaTeX $ within. + + +#### Build your site + +Right-click the `myst.yml` file in the file browser, and select "Build MyST Project". + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...like last time, a new browser tab opens showing a loading spinner while your site +builds. + +When it's done, you should see your "Hello, world!" message, plus our amazing math +equation, rendered on the page. + + +At the top-right, there is a "Rebuild" button. +::: + + +#### Try some other MyST features and rebuild + +:::{important} +**Keep the tab displaying your website open!** + +If you close this tab, you can always re-open it by right-clicking `myst.yml` and +selecting "Build MyST Project" again. +::: + +MyST offers many useful features for technical publishing, including +[superscripts and subscripts](https://mystmd.org/guide/typography#subscript-superscript), +[keyboard input notation](https://mystmd.org/guide/typography#keyboard-input), +[abbreviations](https://mystmd.org/guide/typography#abbr-role), +[executable code cells](https://mystmd.org/guide/notebooks-with-markdown#code-cell), +[callouts](https://mystmd.org/guide/admonitions) (also known as admonitions), +[math](https://mystmd.org/guide/math), +[figures](https://mystmd.org/guide/figures), +[diagrams](https://mystmd.org/guide/diagrams), +[asides](https://mystmd.org/guide/asides), +[dropdowns, grids, tabs, cards, buttons](https://mystmd.org/guide/dropdowns-cards-and-tabs), +[glossaries](https://mystmd.org/guide/glossaries-and-terms), and more. + +Try out some of these features in your MyST site. + +**Each time you make changes, rebuild the site by clicking "Rebuild" at the top-right of +the site.** + +Make changes, rebuild, and view the result as many time as you need! + + +#### Give your site a title + +Edit your `myst.yml` file by double-clicking it in JupyterLab. + +Uncomment the `title` key and populate a title for your site, e.g. "My site". + +Your config file should now look like this: + +```{code} yaml +:filename: myst.yml +:emphasize-lines: 5 + +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +project: + id: 60e9ac52-956d-4811-800a-68be74a85174 + title: "My site" + # description: + # keywords: [] + # authors: [] + github: https://github.com/mfisher87/myst-exercise + # To autogenerate a Table of Contents, run "myst init --write-toc" +site: + template: book-theme + # options: + # favicon: favicon.ico + # logo: site_logo.png +``` + +**Save and rebuild your site.** + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...the text near the top-left of your site now says "My site" (or whatever you +chose for your title) instead of "index". + +The browser tab should also now be titled "My site". + +But it still says "Made with MyST" at the very top! +::: + + +#### Replace "Made with MyST" text + +"Made with MyST" is the default text that appears at the top of your site if +you don't provide a `logo` or `logo_text`. + +We can update the text at the very top to replace "Made with MyST" by editing +`myst.yml` again and setting `site.options.logo_text`. +First, uncomment `options:`, then add a line underneath it to set `logo_text`. +**Indentation is important**. + +Your config file should now look like this: + +```{code} yaml +:filename: myst.yml +:emphasize-lines: 14 + +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +project: + id: 60e9ac52-956d-4811-800a-68be74a85174 + title: "My site" + # description: + # keywords: [] + # authors: [] + github: https://github.com/mfisher87/myst-exercise + # To autogenerate a Table of Contents, run "myst init --write-toc" +site: + template: book-theme + options: + logo_text: "My logo text" + # favicon: favicon.ico + # logo: site_logo.png +``` + +**Save and rebuild your site.** + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...the text near at the very top-left of your site now says "My logo text" (or whatever you +chose for your logo text) instead of "Made with MyST". +::: #### 🧠 What do we know now? -TODO +* `myst.yml` controls what the site looks like, including the title, logo, logo text, and more. +* The `index.md` file is the "home page" for our site by default. +* The development loop for a MyST site in JupyterLab looks like: + * Right-click `myst.yml` and "Build MyST Project" + * In the newly opened browser tab, you can view a preview of your MyST site. + * Change your site content by editing `myst.yml`, Markdown files, or Notebooks. + * View the results of those changes by clicking "Rebuild" at the top of your site preview. ## Building a PDF with MyST From abf1150960c86d4778e6cd09347b6938227b64af Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 20 Nov 2025 19:34:25 -0700 Subject: [PATCH 12/15] Add transition sentence Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com> --- modules/05-sharing-and-publishing/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 4ec2c12..eefd01b 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -74,6 +74,8 @@ Directives are like functions that can receive Markdown content, for example an callout's text. Roles are just like directives, except they are _inline_ with other Markdown text. +Let's jump right into a quick example of how this functionality works. + #### Example `{glossary}` directive and `{term}` role From 308c6301fccdd98984e9b8376112c93dfe5209e3 Mon Sep 17 00:00:00 2001 From: Matt Fisher <3608264+mfisher87@users.noreply.github.com> Date: Thu, 20 Nov 2025 19:36:24 -0700 Subject: [PATCH 13/15] Move mini-exercise prompt above example content Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com> --- modules/05-sharing-and-publishing/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index eefd01b..748fc83 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -78,6 +78,12 @@ Let's jump right into a quick example of how this functionality works. #### Example `{glossary}` directive and `{term}` role +:::{tip} 💪 Mini-exercise +:icon: false + +Try changing the code for the directive and role in the example below and immediately +observe the results. +::: ```{myst} :::{glossary} @@ -90,12 +96,6 @@ Directives can include **_rich_** Markdown content. Try hovering over the word "Term" to see a definition. ``` -:::{tip} 💪 Mini-exercise -:icon: false - -Try changing the code for the directive and role in the example above and immediately -observe the results. -::: ### MySTMD, the software From 774bdc7d958dd45ab4f7cd1f6f2970a3ad8660f3 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 20 Nov 2025 19:39:15 -0700 Subject: [PATCH 14/15] More explicit TODO Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com> --- modules/05-sharing-and-publishing/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 748fc83..87bce25 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -156,8 +156,8 @@ After a few seconds, the build will complete and you can see your fully-built si ### 💪 Exercise A: Build _this_ MyST website in JupyterLab -_TODO_: Will the participants already have the workshop cloned? Or does that need to be -a step here? +_TODO_: Step to clone workshop repo as a drop-down or link to reference page (for +participants who may come in late and miss these instructions from earlier modules) #### Navigate to the correct directory in the file browser From 6c2038692164013cef9fc5a9e910f74a06385e5d Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 20 Nov 2025 19:45:59 -0700 Subject: [PATCH 15/15] Move "The normal way" MyST build instructions into a dropdown Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com> --- modules/05-sharing-and-publishing/index.md | 45 ++++++++++------------ 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 87bce25..9e0d57d 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -111,14 +111,30 @@ MyST and Jupyter Notebook format). ## Building a website with MyST -### The normal way +As workshop participants, you have access to CryoCloud, which provides a JupyterLab +instance with MyST pre-installed. +CryoCloud also comes with a special configuration for building a MyST site without the +use of the terminal. -:::{important} -Because we're working in CryoCloud for this workshop, this section is provided for -informational purposes. -We'll be following the instructions below for using MyST in JupyterLab. +To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). + +:::{important} 👀 You should notice... +:class: simple +:icon: false + +...when you trigger the build as specified in the instructions linked above, a loading +screen is displayed. + +After a few seconds, the build will complete and you can see your fully-built site! ::: +:::{note} The normal way +:class: dropdown + +Because we're working in CryoCloud for this workshop, we'll be following the +instructions above for using MyST in JupyterLab. +If you're interested to know how to use MyST outside of JupyterLab, read on! + With MySTMD [installed](https://mystmd.org/guide/installing), you can build a MyST website from source with one command: @@ -132,25 +148,6 @@ rebuild your site any time you change its content: ```bash myst start ``` - - -### In JupyterLab - -As workshop participants, you have access to CryoCloud, which provides a JupyterLab -instance with MyST pre-installed. -CryoCloud also comes with a special configuration for building a MyST site without the -use of the terminal. - -To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). - -:::{important} 👀 You should notice... -:class: simple -:icon: false - -...when you open the URL specified in the instructions above, a loading screen is -displayed. - -After a few seconds, the build will complete and you can see your fully-built site! :::