Merge pull request #20 from Openscapes/setup-explore

Setup explore

_freeze/lessons/demo/execute-results/html.json

@@ -1,8 +1,8 @@
 {
-  "hash": "8e025b84a8a826d468ca12847c41dce8",
+  "hash": "a1c645e528cd68c7ae21d914002f5526",
   "result": {
     "engine": "knitr",
-    "markdown": "---\ntitle: \"`demo.qmd` aka Quarto Practice\"\n---\n\n\nQuarto enables you to weave together content and executable code into a finished document.\n\nThis `demo.qmd` file has Markdown-formatted text, examples for adding hyperlinks and inserting images with alt-text, and a Python code chunk.\n\n## Edit and preview a demo.qmd file\n\n-   Headers. Headers are powerful in Quarto because they let you organize on the side of the page. They let you share a specific section of a page by copying the URL\n-   hyperlink something (cite the Cookbook and hyperlink it). Hyperlinking is done like this; lets you cite and give credit\n-   inspect this image with alt-txt\n-   Python code. manage echo, run\n\n## Task 1a: Edit a `.qmd` page\n\n*TODO: Edit down to what we need, duplicated under each name header*\n\n::: callout-note\nOnly make changes to the section under your name header (to prevent conflicts at a later stage)\n:::\n\nNow let's practice Markdown in this Quarto file and commit an edit to this file.\n\n### Stefanie\n\nYour first edit? Fix this tpyo.\n\n#### **Headers**\n\nWe can make headers using `## Name`, `### Name`, etc. Headers are powerful in Quarto because they let you organize your content. You can share a specific subsection of a page by copying its URL.\n\n#### **Hyperlinks**\n\nWe can make hyperlinks using the `[]()` pattern: you name the hyperlink in `[]` and put the URL in `()`. For example, here's a link to [Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html). Hyperlinking lets us cite and give credit to our sources, like the NASA Earthdata Cloud Cookbook ([Barrett et al.](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)).\n\n#### **Images**\n\nWe can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. The `[]` contain the caption and `()` contain the path to the image file. Other attributes like image size, alt text, and a hyperlink, are also set in this example:\n\n[![The Openscapes logo](/images/openscapes_hex.png){fig-alt=\"Openscapes logo. A hexagonal shape with orange border, yellow background, the word openscapes in orange above a cartoon evoking a landscape of data plots\" width=\"150\"}](https://openscapes.org/)\n\n#### **Code**\n\nWhen you **Render**, a document will be generated that includes both content and the output of embedded code. You can embed code like this:\n\n*TODO: day before clinic, make this Python code (don't add screenshot - fewer files to for folks to get distracted with, lighter weight repo)*\n\n\n::: {.cell}\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] 4\n```\n\n\n:::\n:::\n\n\nYou can add options to executable code. The `echo: false` option disables the printing of code (only output is displayed).\n\n### Julie\n\nFix this tpyo.\n\n### Andy\n\nFix this tpyo.\n\n## Your turn!\n\nChange or add something to this file under your Name header and save the file.\n",
+    "markdown": "---\ntitle: \"`demo.qmd` Quarto Practice\"\n---\n\n\nQuarto enables you to weave together content and executable code into a finished document.\n\nThis `demo.qmd` file has Markdown-formatted text, examples for adding hyperlinks and inserting images with alt-text, and a Python code chunk.\n\n-   Headers. Headers are powerful in Quarto because they let you organize on the side of the page. They let you share a specific section of a page by copying the URL\n-   hyperlink something (cite the Cookbook and hyperlink it). Hyperlinking is done like this; lets you cite and give credit\n-   inspect this image with alt-txt\n-   Python code. manage echo, run\n\nStef will demo then it's your turn.\n\n## Task 1a: Edit a `.qmd` page\n\n*TODO: Edit down to what we need, duplicated under each name header*\n\n::: callout-note\nOnly make changes to the section under your name header (to prevent conflicts at a later stage)\n:::\n\nNow let's practice Markdown in this Quarto file and commit an edit to this file.\n\nMake an edit, preview, edit etc\n\n### Stefanie\n\nYour first edit? Fix this tpyo.\n\n#### **Headers**\n\nWe can make headers using `## Name`, `### Name`, etc. Headers are powerful in Quarto because they let you organize your content. You can share a specific subsection of a page by copying its URL.\n\n#### **Hyperlinks**\n\nWe can make hyperlinks using the `[]()` pattern: you name the hyperlink in `[]` and put the URL in `()`. For example, here's a link to [Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html). Hyperlinking lets us cite and give credit to our sources, like the NASA Earthdata Cloud Cookbook ([Barrett et al.](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)).\n\n#### **Images**\n\nWe can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. The `[]` contain the caption and `()` contain the path to the image file. Other attributes like image size, alt text, and a hyperlink, are also set in this example:\n\n[![The Openscapes logo](/images/openscapes_hex.png){fig-alt=\"Openscapes logo. A hexagonal shape with orange border, yellow background, the word openscapes in orange above a cartoon evoking a landscape of data plots\" width=\"150\"}](https://openscapes.org/)\n\n#### **Code**\n\nWhen you **Render**, a document will be generated that includes both content and the output of embedded code. You can embed code like this:\n\n*TODO: day before clinic, make this Python code (don't add screenshot - fewer files to for folks to get distracted with, lighter weight repo)*\n\n\n::: {.cell}\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] 4\n```\n\n\n:::\n:::\n\n\nYou can add options to executable code. The `echo: false` option disables the printing of code (only output is displayed).\n\n### Julie\n\nFix this tpyo.\n\n*TODO: copy activities text under each participant heading when it's settled*\n\n### Andy\n\nFix this tpyo.\n\n## Your turn!\n\nChange or add something to this file under your Name header and save the file.\n",
     "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"

index.qmd

@@ -5,9 +5,9 @@ subtitle: "Share open-source tutorials, onboarding docs, and much more"
 
 ## Welcome
 
-It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub](http://github.com). This is fairly new and incredibly cool. This Clinic is an example of a Quarto website --- a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you and/or your colleagues use for analyses, whether or not you write code.
+It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub](http://github.com). This Clinic is an example of a Quarto website --- a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you and/or your colleagues use for analyses, whether or not you write code.
 
-Creating and editing websites with Quarto can be done without knowing R, Python or HTML, CSS, etc, however, Quarto integrates with these tools so you can make your websites as complex and beautiful as you like as you see examples and reuse and remix from others in the open science community.
+The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto is a common place for us to collaborate - across Python and R languages and varied levels of coding expertise, and accessibility and inclusion are centered in the Quarto design.
 
 **To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub.
 
@@ -17,43 +17,30 @@ Creating and editing websites with Quarto can be done without knowing R, Python
 
 **Outcomes:** Mentors build skills and are more equipped and empowered to contribute. This is a new clinic we can reuse and build on.
 
-**Process:** A 1.5-hr clinic with demo's and hands-on practice to guide folks through contributing to existing Quarto sites & books. Analogous to our GitHub Clinic. The clinic content is contained in this website that is built with Quarto on GitHub; there are no accompanying slide decks.
+**Process:** A 1.5-hr clinic that can be used to teach or as self-paced learning. with demo's and hands-on practice to guide folks through contributing to existing Quarto sites & books. Analogous to our GitHub Clinic. The clinic content is contained in this website that is built with Quarto on GitHub; there are no accompanying slide decks.
 
-1.  Introduction to Quarto using the 2i2c Openscapes JupyterHub.
+1.  Quarto Workflow: Use the 2i2c Openscapes JupyterHub to explore this clinic website and its source repository on GitHub, practice contributing to this site by editing a Quarto file or adding a new Jupyter Notebook and previewing the changes.
 
-2.  GitHub Workflow: How to clone the repo for this site, make a branch to work in, edit, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step.
+2.  GitHub Workflow: Clone the repository for this site, make a branch to work in, edit, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step.
 
 ## What is Quarto?
 
-[Quarto](https://quarto.org) helps you have your ideas and your code in one place, and present it in a beautiful way.
+Quarto helps you have your ideas and your code in one place, and present it in a beautiful way.
 
 > Quarto is an open-source scientific and technical publishing system built on Pandoc. You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books, presentations, and more.
 
-Quarto can be used to create dynamic content with Python, R, Julia, and Observable through your favorite IDE like JupyterHub or RStudio.
-
-The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto is a common place for us to collaborate - across Python and R languages and varied levels of coding expertise and accessibility and inclusion are centered in the Quarto design.
-
-## What is this Clinic?
-
-This is a 1.5-hour clinic that can be used to teach or as self-paced learning.
-
-We introduce Quarto by exploring this clinic website, and practicing the basic Quarto workflow using the 2i2c Openscapes JupyterHub for editing your website and GitHub in the browser to review proposed updates.
+Quarto can be used to create dynamic content with Python, R, Julia, and Observable through your favorite IDE like JupyterHub or RStudio. Creating and editing websites with Quarto can be done without knowing R, Python or HTML, CSS, etc, however, Quarto integrates with these tools so you can make your websites as complex and beautiful as you like as you see examples and reuse and remix from others in the open science community.
 
 [Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials!
 
 ## Example Quarto sites
 
-A few Quarto websites from Openscapes - so far we have been using Quarto for documentation using Quarto and Markdown files and Jupyter Notebooks.
-
+-   [NASA Openscapes](https://nasa-openscapes.github.io/)
 -   [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/)
 -   [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/)
--   [Champions Lessons Series](https://openscapes.github.io/series)
+-   [Openscapes Champions Lessons Series](https://openscapes.github.io/series)
 -   [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/)
 -   [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/)
 -   [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel
 
-## About
-
-[Openscapes](https://openscapes.org) is about better science for future us. We help researchers reimagine data analysis, develop modern skills that are of immediate value to them, and cultivate collaborative and inclusive research teams as part of the broader global open movement.
-
-We're developing this tutorial to help folks with different levels of technical skills use [Quarto](https://quarto.org) for documentation and tutorial building. This tutorial was originally created for several different audiences: [NASA-Openscapes](https://nasa-openscapes.github.io) researcher support engineers using Python, communications directors at organizations promoting open science who do not identify as coders, and fisheries scientists curious about transitioning from RMarkdown. We're hoping it's useful to folks with backgrounds as wide as these; if you find it useful or have suggestions for improvement, please let us know by clicking "Edit this page" or "Report an issue" at the upper right side of any page.
+See many more examples at the [Quarto gallery](https://quarto.org/docs/gallery/)!

lessons/demo.qmd

@@ -1,18 +1,18 @@
 ---
-title: "`demo.qmd` aka Quarto Practice"
+title: "`demo.qmd` Quarto Practice"
 ---
 
 Quarto enables you to weave together content and executable code into a finished document.
 
 This `demo.qmd` file has Markdown-formatted text, examples for adding hyperlinks and inserting images with alt-text, and a Python code chunk.
 
-## Edit and preview a demo.qmd file
-
 -   Headers. Headers are powerful in Quarto because they let you organize on the side of the page. They let you share a specific section of a page by copying the URL
 -   hyperlink something (cite the Cookbook and hyperlink it). Hyperlinking is done like this; lets you cite and give credit
 -   inspect this image with alt-txt
 -   Python code. manage echo, run
 
+Stef will demo then it's your turn.
+
 ## Task 1a: Edit a `.qmd` page
 
 *TODO: Edit down to what we need, duplicated under each name header*
@@ -23,6 +23,8 @@ Only make changes to the section under your name header (to prevent conflicts at
 
 Now let's practice Markdown in this Quarto file and commit an edit to this file.
 
+Make an edit, preview, edit etc
+
 ### Stefanie
 
 Your first edit? Fix this tpyo.
@@ -58,6 +60,8 @@ You can add options to executable code. The `echo: false` option disables the pr
 
 Fix this tpyo.
 
+*TODO: copy activities text under each participant heading when it's settled*
+
 ### Andy
 
 Fix this tpyo.

lessons/index.qmd

@@ -1,21 +1,25 @@
 ---
-title: Lessons
+title: Practice
 ---
 
+*TODO: Drastically reduce this page's text. Get to the doing. This index page should say, hey here's 2 things we'll practice - Edit a Quarto site, and Contribute via GitHub. Here's the Basic Workflow*
+
 ## Basic Workflow
 
-How do you work in Quarto? You can use whichever tool you're comfortable with (RStudio, Jupyter, GitHub, VS Code, etc). Developing your quarto site will have the same basic workflow, no matter which tool you use. It is very iterative, and each is explored more below. 
+How do you work in Quarto? You can use whichever tool you're comfortable with (Jupyter, RStudio, GitHub, VS Code, etc). Developing your Quarto site will have the same basic workflow, no matter which tool you use. It is very iterative.
 
 1.  Authoring: write text, code, images, etc in a file. Supported files include `.md`, `.Rmd`, `.qmd`, `.ipynb`...
 2.  Update `_quarto.yml` as needed (for example, if you've created a new file you'd like included in your site)
-3.  Render individual files and/or the whole website 
+3.  Render individual files and/or the whole website
 4.  Repeat, repeat, repeat
-5.  Commit and push your website to GitHub, your updates will publish automatically! 
+5.  Commit and push your updates to GitHub, they will publish automatically!
 6.  Repeat all of the above to make the website as you'd like!
 
 ## Authoring
 
-As an author, you have a lot of options of how your text will be formatted, arranged, and interlinked. You will be writing in Markdown, which is a lightweight text formatting language. The Quarto documentation about authoring introduces [markdown-basics](https://quarto.org/docs/authoring/markdown-basics.html) that will get you started. Also see Mine Çetinkaya-Rundel's [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/).
+*TODO: change "authoring" heading? Move to "Edit a Quarto site"*
+
+As an author, you have a lot of options of how your text will be formatted, arranged, and interlinked. You will be writing in Markdown, which is a lightweight text formatting language. The Quarto documentation about authoring introduces [markdown-basics](https://quarto.org/docs/authoring/markdown-basics.html) that will get you started.
 
 Each page of our site has a similar first few lines - this YAML, like we saw in our `_quarto.yml` and it is indicated by two sets of 3 dashes `---` :
 
@@ -27,18 +31,18 @@ title: My title
 
 You're able to add more features to individual pages by including it in the YAML, which for the most part here only includes a title. See [Quarto excecution options](https://quarto.org/docs/computations/execution-options.html) for more information of what you can include in the YAML.
 
-
 ## Update `_quarto.yml`
 
+*TODO: move this to Edit a Quarto site: Preview your updates (Regroup, 10 min)*
+
 Let's have a closer look at the `_quarto.yml` file.
 
-This type of file (`.yml` or `.yaml`) is written in YAML ("Yet Another Markup Language"). You'll be able to shift the arrangement of webpages by reordering/adding/deleting them in the `_quarto.yml` file following the patterns you see in this example. 
+This type of file (`.yml` or `.yaml`) is written in YAML ("Yet Another Markup Language"). You'll be able to shift the arrangement of webpages by reordering/adding/deleting them in the `_quarto.yml` file following the patterns you see in this example.
 
-![`_quarto.yml` and website side-by-side](images/quarto-yml-site-side-by-side3.png){alt="_quarto.yml and website side-by-side" fig-align="center" width="95%"}
+![\_quarto.yml and website side-by-side](images/quarto-yml-site-side-by-side3.png){fig-align="center" width="95%"}
 
 Notice that there are multiple ways in the `_quarto.yml` for you to include a file in your website. For example, in the above image, the "First Observations" we see in the left sidebar of the published website (right image) is represented in `_quarto.yml` (left image) over two lines, with line 36 indicating the file reference and line 37 indicating the text to show up in the left sidebar. However, "From RStudio" is only represented in one line of `_quarto.yml`, on line 43. This represents two strategies for including a file in your website. By default, the title of a specified file will show up in the website's sidebar, which is what is happening with the "From RStudio" example. If you would like more control over what is written in the sidebar vs the title of your files, then the approach we took with "First Observations" is what you'll want to do: you'll see that only "First Observations" shows up in the sidebar as we specified in `_quarto.yml`, but the page's title says "First Observations & Setup" (which in our preference was too long for the sidebar).
 
-:::{.callout-note}
+::: callout-note
 As you modify `_quarto.yml`, the most important thing to know is that **spacing matters**. Pay attention to whether text is indented by one, two, four, or other spaces, and make sure you follow it; if your site is not looking as expected it is likely a silent error in your YAML. Some text editors like RStudio provide debugging support for YAML and are highly recommended to save you time and heartache.
 :::
-