Merge pull request #18 from Openscapes/bookdown-quarto

explore.qmd

@@ -2,7 +2,7 @@
 title: Explore and setup
 ---
 
-With this tutorial, we have a working example website that we will explore together. We'll learn a few rules and look for patterns to get an understanding of what things do to help you start customizing and making it your own. And you can continue to use this website as a reference after the tutorial, along with [Quarto](https://quarto.org) documentation.
+With this tutorial, we have a working example website that we will explore together. We'll learn a few rules and look for patterns to get an understanding of what things to do to help you start customizing and making it your own. And you can continue to use this website as a reference after the tutorial, along with [Quarto](https://quarto.org) documentation.
 
 We'll start our exploration online looking at the website architecture and GitHub repository. Then we'll setup a copy for ourselves so that we can modify from a working example, which is a great way to learn something new. We'll set it up so that any modifications (commits) will automatically be republished via GitHub Actions. Subsequent chapters will describe how to modify your repo using different tools (browser, RStudio, Jupyter).
 
@@ -13,7 +13,7 @@ We'll start our exploration online looking at the website architecture and GitHu
 [This website](https://openscapes.github.io/quarto-website-tutorial/) has 5 things you can see on the left sidebar:
 
 -   Welcome
--   Exploring our website
+-   Exploring and setup
 -   Quarto workflows
 -   Learning more
 -   Transition from Rmd
@@ -22,13 +22,13 @@ Most of these are pages, but you'll see that "Quarto Workflows" has an arrow; it
 
 ### The website's repo
 
-Let's go to this website's GitHub repository (also called a "repo"), [**https://github.com/openscapes/quarto-website-tutorial**](https://github.com/openscapes/quarto-website-tutorial){.uri}. You can also click there from this page this tutorial website by clicking the GitHub octocat icon underneath the Openscapes logo in the left navbar (click it holding command on Mac, or control on a PC to open it in a different tab in your browser).
+Let's go to this website's GitHub repository (also called a "repo"), [**https://github.com/openscapes/quarto-website-tutorial**](https://github.com/openscapes/quarto-website-tutorial){.uri}. You can also click there from any page in this tutorial website by clicking the GitHub octocat icon underneath the Openscapes logo in the left navbar (click it holding command on Mac, or control on a PC to open it in a different tab in your browser).
 
 **Have a look at the filenames.** We can recognize the names of the webpages we've seen above, and they have red arrows marking them in the image below. You'll see the "quarto-workflows" folder and the rest in this site are `.qmd` files, which are plain text Quarto files that can combine Markdown text with code. `index.qmd` is the home page. If you click inside "quarto-workflows" you'll see a mix of filetypes!
 
 ![quarto-website-tutorial GitHub repository with files for webpages marked with red arrows](images/quarto-files-github.png){fig-alt="Screenshot of files on GitHub with red arrows identifying the files that we saw in the left sidebar" fig-align="center" width="80%"}
 
-**The `_site` folder** has html files with names that should be familiar: they match the `.    md` files we were just exploring. This folder is where Quarto stores files to build the website.
+**The `_site` folder** has html files with names that should be familiar: they match the `.md` files we were just exploring. This folder is where Quarto stores files to build the website.
 
 ## `_quarto.yml` intro
 
@@ -48,7 +48,7 @@ Other options of potential interest:
 
 -   [2021-Cloud-Hackathon](https://github.com/NASA-Openscapes/2021-Cloud-Hackathon)
 -   [2022-SWOT-Ocean-Cloud-Workshop](https://github.com/podaac/2022-SWOT-Ocean-Cloud-Workshop)
--   [Approach-Guide](https://openscapes.github.io/approach-guide)
+-   [Openscapes Approach-Guide](https://openscapes.github.io/approach-guide)
 
 Next, follow [these steps to fork and setup your repo with GitHub Actions](https://github.com/thefaylab/lab-manual/wiki/Quick-steps-to-making-a-copy-of-the-lab-manual-&-publishing-it) from Gavin Fay, using the repo you chose. These instructions will take \~5 minutes.
 
@@ -78,7 +78,7 @@ Note: if you're comfortable cloning the new repository and copying files into it
 
 If you've used the GitHub uploader, you'll need to set up GitHub publishing separately. We'll do this in a few steps: we'll set up a GitHub Action within your repo, and create a `gh-pages` branch.
 
-First, the GitHub Action. Go back to your main view of your GitHub repository by clicking on the name of your repository in blue at the top-left (the url in your browser window should say https://github.com/username/repo-name).
+**First, the GitHub Action**. Go back to your main view of your GitHub repository by clicking on the name of your repository in blue at the top-left (the url in your browser window should say https://github.com/username/repo-name).
 
 Next to the green code button, click Add file \> Create new file. Name it exactly this: `.github/workflows/quarto-publish.yml` . In detail: start by typing the `.` with `github` and when you type the `/` it will give you a new text box to type `workflows` (plural!), then another `/`, and finally, `quarto-publish.yml`.
 
@@ -118,7 +118,7 @@ jobs:
 
 Commit this to save your new `quarto-publish.yml` file. This is your GitHub Action.
 
-Next, we'll create a new `gh-pages` branch. Go back to the main view of your GitHub repository. On the far left from the green "Code" button, click the button that says "main". In the pull-down menu, type `gh-pages` - all lowercase, with a hyphen. Click the bold text that says "Create branch: gh-pages from main".
+**Next, we'll create a new `gh-pages` branch**. Go back to the main view of your GitHub repository. On the far left from the green "Code" button, click the button that says "main". In the pull-down menu, type `gh-pages` - all lowercase, with a hyphen. Click the bold text that says "Create branch: gh-pages from main".
 
 Now click on the Settings tab in the top right of your repository. On the left sidebar, click Pages. At the top of Pages under "Source", select `gh-pages` root, and press Save. You'll then see a green highlighted text saying that your site is published at a "github.io" url.
 

index.qmd

@@ -5,7 +5,7 @@ subtitle: "Create open-source tutorials, onboarding docs, and much more"
 
 ## Welcome {#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 very new and incredibly cool. This tutorial is an example of a quarto website --- it is 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 is very new and incredibly cool. This tutorial is an example of a quarto website --- it is 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 websites with Quarto can be done without knowing R, Python or HTML, CSS, etc, and that's where we'll start. 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 community. This tutorial borrows heavily from a lot of great tutorials and resources you should check out too -- there are links throughout.
 
@@ -16,28 +16,30 @@ Quarto helps you have your ideas and your code in one place, and present it in a
 **Quarto unifies and extends the RMarkdown ecosystem** - it unifies by combining the functionality of R Markdown, bookdown, distill, xaringian, etc into a single consistent system. And it extends in several ways: all features are possible beyond R too, including Python and Javascript. It also has more “guardrails”: accessibility and inclusion are centered in the design. Quarto is for people who love RMarkdown, and it's for people who have never used RMarkdown. 
 
 
-The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto has been a common place for us to collaborate - across R and Pyahon languages and coding expertise. 
+The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto has been a common place for us to collaborate - across R and Python languages and coding expertise. 
 
 ## What is this tutorial?
 
 This is a 1-hour tutorial that can be used to teach or as self-paced learning. 
 
 We introduce Quarto by exploring this tutorial website, and practicing the basic Quarto workflow using different tools (GitHub browser, RStudio, and Jupyter) for editing your website.
 
-We'll start off from the browser so you don't need to install any additional software, however this approach is very limited and you will soon outgrow its capabilities. If you don't already have a workflow and to edit files and sync to GitHub from your computer, I recommend RStudio. You don't need to know R to use RStudio, and it has powerful editor features that make for happy workflows.
+We'll start off from the browser so you don't need to install any additional software, however this approach is very limited and you will soon outgrow its capabilities. If you don't already have a workflow to edit files and sync to GitHub from your computer, I recommend RStudio. You don't need to know R to use RStudio, and it has powerful editor features that make for happy workflows.
 
 [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 - wo far we have been using Quarto for documentation using Quarto and Markdown files and Jupyter Notebooks.
+A few Quarto websites from Openscapes - so far we have been using Quarto for documentation using Quarto and Markdown files and Jupyter Notebooks.
 
 -   [Champions Lessons Series](https://openscapes.github.io/series)
 -   [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/)\
 -   [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/)
+-   [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 of different 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.
+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.

learning-more.qmd

@@ -6,6 +6,8 @@ title: Learning more
 
 An excellent overview: **Reproducible authoring with Quarto** - Mine Çetinkaya-Rundel, Feb 2022
     -   [slides](https://mine-cetinkaya-rundel.github.io/2022-repro-toronto/#/title-slide), [youtube](https://www.youtube.com/watch?v=6p4vOKS6Xls)
+
+[A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/) in June 2022, from Mine Çetinkaya-Rundel.
 
 ### Examples in the wild: 
 -   [Openscapes Champions Lessons Series](https://openscapes.github.io/series)
@@ -16,4 +18,4 @@ See many more examples at the [quarto gallery](https://quarto.org/docs/gallery/)
 
 ### Inspiration
 
-Are you making onboarding documentation? Check out [The Fay Lab Manual](https://thefaylab.github.io/lab-manual/) for inspiration on structure - you could also start there and make it your own.
+Are you making onboarding documentation? Check out [The Fay Lab Manual](https://thefaylab.github.io/lab-manual/) (now in Quarto!) for inspiration on structure - you could also start there and make it your own.

quarto-workflows/browser.md

@@ -10,7 +10,7 @@ Here's an example of editing content on an existing page.
 
 Let's change the date on the home page of this website.
 
-In your repository, navigate to `index.md`. Then, click the pencil icon in the top left to edit directly.
+In your repository, navigate to `index.md`. Then, click the pencil icon in the top right to edit directly.
 
 ![](images/github-edit-index.png){fig-align="center" width="95%"}
 
@@ -24,11 +24,11 @@ Our `index.md` file is written in Markdown, which enables you to make simple tex
 
 ## Commit and publish
 
-Commit your changes by scrolling to the bottom of the page and writing a commit message - a note to yourself and others about what happened. Write your commit message and then click the green "Commit changes" button.
+Commit your changes by scrolling to the bottom of the page and writing a commit message - a note to yourself and others about what changes you made. Write your commit message and then click the green "Commit changes" button.
 
 ![](images/github-commit.png){fig-align="center"}
 
-Now, click back to the main page of your GitHub repository. You should see the orange dot [confirming your website is published](explore.qmd#confirm). You'll have to wait for the GitHub Action to tell quarto to build your site for you to see the update, but it will be there!
+Now, click back to the main page of your GitHub repository. You should see the orange dot [confirming your website is published](../explore.qmd#confirm). You'll have to wait for the GitHub Action to tell quarto to build your site for you to see the update, but it will be there!
 
 ## Limitations
 

quarto-workflows/index.qmd

@@ -28,11 +28,11 @@ How do you work in Quarto? You can use whichever tool you're comfortable with (R
 5.  Commit and push your website to GitHub, your updates will publish automatically! 
 6.  Repeat all of the above to make the website as you'd like!
 
-Note: if editing from your internet Browser we won't render in Step 3 will not be separate but combined with Step 5, which will only require a commit, not a push)
+Note: if editing from your internet browser we won't render in Step 3. That step will not be separate, but combined with Step 5, which will only require a commit, not a push.
 
 ## 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.
+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/).
 
 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 `---` :
 

quarto-workflows/jupyter.md

@@ -230,7 +230,7 @@ So, your normal workflow for creating and running code blocks in your Jupyter No
 
 ## Quarto render
 
-So far we have used **Quarto preview** view our website as we develop it. **Quarto render** will build the html elements of the website that we can see when we preview. Rendering will format the markdown text and code nicely as a website (or however is indicated in the `_quarto.yml`).
+So far we have used **Quarto preview** to view our website as we develop it. **Quarto render** will build the html elements of the website that we can see when we preview. Rendering will format the markdown text and code nicely as a website (or however is indicated in the `_quarto.yml`).
 
 By default, Quarto render does not execute code in a Jupyter notebook. It will never run .ipynb files unless you tell it to.
 

quarto-workflows/rstudio.qmd

@@ -2,7 +2,7 @@
 title: From RStudio
 ---
 
-The RStudio software (called an IDE, integrated development environment) is an excellent way to edit files and interface with GitHub. Plus, as it is made by the same folks who make Quarto, it has many integrated features for streamlining your workflow with Quarto, including how it previews your edits and provides debugging support for yaml! [Quarto\'s RStudio tutorials](https://quarto.org/docs/get-started/hello/rstudio.html) has great instructions on getting started with JupyterLab, including computations and authoring.
+The RStudio software (called an IDE, integrated development environment) is an excellent way to edit files and interface with GitHub. Plus, as it is made by the same folks who make Quarto, it has many integrated features for streamlining your workflow with Quarto, including how it previews your edits and provides debugging support for yaml! [Quarto\'s RStudio tutorials](https://quarto.org/docs/get-started/hello/rstudio.html) has great instructions on getting started with RStudio, including computations and authoring.
 
 Here is what you'll need to do to set up and use RStudio with Quarto.