Accompanying video tutorial

Accompanying video tutorial

1 Install your tools

First things first, let’s get your tools set up: RStudio & Quarto. RStudio is the desktop application that we’ll work in, while Quarto is what will build the website. We’ll use the Quarto visual editor to write and format the content for our website pages. While there’s no installation required for Netlify, you will need to create a free account.

Download and install R and RStudio Desktop from Posit. Note that R and RStudio are different things. R is a programming language often used for statistics, data analyses, and data visualizations. RStudio is the integrated development environment (IDE), or desktop application, that has nice point-and-click features. Although we won’t directly use R, we still need to download it so we can use RStudio.

Quarto will automatically be installed with RStudio. The version of Quarto installed with RStudio may not be the latest version, so you can optionally install Quarto separately. Quarto is an open-source publishing system, developed by the same company (Posit) that develops RStudio so they integrate very nicely.

RStudio and Quarto are powerful tools that can create a lot more than just websites. However, in this tutorial, I assume you’ve never used either before. I’ll introduce only the components necessary to get you started with a simple website.

2 Create a Quarto website

Open RStudio, click the Create a project button to open the New Project Wizard, and then select New Directory.

Select Quarto Website as the project type.

A “directory” is basically the same thing as a computer folder. Choose what you want to name your folder (probably the same as your website name)¹, browse to where you want this folder to live, check the Use visual markdown editor button, and then click Create Project.

We should now be in a new project that has index.qmd open in visual editor mode, and some new things in our Files pane. We’ll get to what these files are in the next Understand the files section. But first, let’s take a look at what the default website looks like. Open the Build pane, and then click the Render Website button.

Once the website renders, the bottom right pane will switch from Files to Viewer and display the website preview. Click the Show in new window button to open this preview in your default browser.

3 Understand the files

Cool, now you know RStudio and Quarto are correctly installed and you can render a simple website! Before we start customizing your website, let’s take a look at what files came pre-loaded with this default website.

Our Files pane should include:

├── _quarto.yml         # Website configuration file
├── about.qmd           # About page
├── index.qmd           # Landing page
├── my-website.Rproj    # RStudio project config file
└── styles.css          # CSS style sheet

• _quarto.yml is a special file that configures the website options like the title, which .qmd files to include, navigation, styling, etc. Do not rename this file. Quarto needs this file to render your website.

• .qmd files are Quarto documents where you’ll write your webpage content.

  • index.qmd is the landing/home page of the website. Do not rename this file. Netlify needs this file to publish your website.

  • about.qmd is another page on the website. It can be renamed or removed.

• Ignore the .Rproj file, which is a RStudio project configuration file.

• styles.css is a where you can customize the style of specific elements of your website using CSS. Ignore this until you’re ready for more advanced customization. We’ll get to styling our simple website in the Style your website section.

4 Edit the home page

Open index.qmd and notice the box at the top of the document that has title: "my-website" sandwiched between two sets of three dashes ---. This is called the YAML header, which contains the metadata for the document. The only metadata we currently have is the webpage title. Each YAML entry consists of key: value pairs. The colon and space are required. Be careful with indentation, it can be quite fussy.

Write all content for the webpage below this YAML. Use the formatting toolbar at the top of the document to format text, create headings, or insert images, lists, and tables.

When working on a single page, I like to check the Render on Save option so that the website preview updates every time I save the .qmd file. Alternatively, click the Render button, which saves the file and updates the preview.

5 Edit the about page

Quarto makes it easy to create a simple, professional about page for a person, organization, or pets 😏. Add the about: option in the YAML to use one of the five special templates previewed below (examples from Quarto docs).

---
title: "Mai, Tai, and Skye"
image: images/couch-kits.JPG
about:
  template: jolla
  links:
    - icon: instagram
      text: Instagram
      href: https://www.instagram.com/piggies.and.kits
---

6 Add a new page

Now that you’ve updated the two pages that came with the default Quarto website project, it’s time to add another page!

Click the New file button and select Quarto document. This will open a dialog box to name your file. After clicking OK, a blank .qmd file with your chosen name will open.

7 Update _quarto.yml

To make sure the new page is included on your website, you must add it to your _quarto.yml file.

This is also the place to change how the website title and page links are displayed in the navigation bar.

• Under navbar:
  • left: means these links will appear on the left side of the navbar. You can also use the right: option to show certain links on the right side.
    • href: must be the filename of the .qmd
    • text: is the link to that page.

website:
  title: "MTS -- The Best Kits!"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: birthdays.qmd
        text: Birthday

website:
  title: "my-website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

8 Style your website

Now that you’ve got a few pages set up, it’s time to customize the look and feel of your site! Quarto websites can use any of the 25 themes from the Bootswatch project.

In _quarto.yml, under the html: theme: option, replace the default cosmos with your theme of choice. Make sure the theme value is all lowercase.

format:
  html:
    theme: minty
    css: styles.css

If you’re ready to do more advanced customization, you can open and edit styles.css. See the Quarto docs on theming.

9 Publish to Netlify

Once you’re happy with your website, it’s time to publish it so anyone can view it on the live web! We’re going to use Netlify because it’s free and very simple to use with their drag and drop deployment tool.

Remember back when we first rendered the website, Quarto created the new _site folder? This is what we’ll drop into the Netlify deployment tool. _site contains all the HTML files, style sheets, images, and other resources that make up the website. You must drop the entire _site folder into the Netlify tool. Dropping the contents of the folder will error and Netlify will tell you “Please drop a folder containing an index.html file.”

After it uploads, we’ll look at the live website and change the site name.

10 Update your website

When you make updates to your website, be sure to Render Website under the Build pane of RStudio to update the entire _site folder.

Log in to Netlify, click on your site, open the Deploys tab, and upload the _site folder.

Once it says Published, go check out your changes!

Recording of live code review session

New tips and tricks I learned

• Use goodpractice::gp() to run a check for many good practices in R package development.

• {cli} has special inline markup classes.

• // to add a new line in {cli} message. I bet this works with other long string arguments as well.

• usethis::use_package_doc() generates basic package-level documentation.

• Menu to open file or function: Ctrl + .

Things I did well

• Time and effort to make the user experience (UX) good: video demos, boxes and annotations for videos and screenshots, {pkgdown} website with detailed articles

• Defensive programming: failing early and giving error messages

• Using functions like cat_red_bullet and cet_green_check to set nice, informative {cli} message symbols

• Consistent styling with {grkstyle}

• Including a URL reference to the exact commit of functions adapted from other packages

• Including data dictionary was nice.

• Generating example data from an R script to make it possible to reproduce.

Things to improve

• Huge package size (not a big deal since using R-Universe instead of CRAN)

• Incorporate testing

• Error messages: take advantage of {cli} inline markup, provide an example of what the code should look like, tell the user if they need to provide something rather than say something is missing

• Better use explaining variables in conditional statements to unravel confusing ifelse logic.

• More consistency with approaches / utilities: base R or tidyverse

• Naming things is so hard! Mixing snake_case and camelCase in the example data and data dictionary.

  • Things to look into: comments responding to Ben Bolker’s Mastodon post, Shannon Pileggi’s post, Emily Riederer’s post, data.table::setattr(), and {units} thanks to Michael McCarthy.

• Be more descriptive with example data: call it washi_example instead of exampleData and include data viz.

• Investigate ggtern overwriting ggplot2 S3 methods warning more closely, resolve or rethrow more helpful warning text instead of using suppressWarnings().

• Write better commit messages following the template: “this commit will…” and use headlines and bullet points.

Notes

There are lots of notes of things Nick would wanted to “get to later” but we ran out of time. I left these notes in just to draw attention to other things we would have looked at more closely given more time.

test_that("create_soils returns appropriate error", {
  expect_snapshot_error(
    create_soils()
  )
})

Tests, snapshots, base pipe:
* use tests and snapshot testing
* depend on R 4.1.0 since |> is used

From 2022 to 2023

The year started off pretty rough for me. This was my second year in this data scientist role where everything (soil science, data management, programming) was new to me. I was disappointed in myself because I only accomplished about half of my 2022 goals and worried that I was also disappointing my supervisor and colleagues. I was wondering if I made a mistake in this career transition from a field-based environmental scientist to a data scientist. On a daily basis, I really struggled with imposter syndrome and worried that I was holding back these important statewide programs and initiatives because I was slow and needed to learn so much on the job.

First rejection

I submitted a talk proposal to present {WaCSE}, my first Shiny app used for a statewide agricultural grant program, at Appsilon’s Shiny Conf. I submitted the abstract at the end of 2022 and got the rejection notice at the end of January 2023. This was my third conference proposal I’ve ever submitted in the four years of my professional career and my first rejection. My learned lesson here was to put more thought into which category I submit to (20-min talk versus showcase section) and make the idea more unique. The feedback from the review committee was that my talk fell under the category “tools to facilitate data access” and there were quite a few of those. This rejection certainly added to my feelings of being an imposter and not deserving my job.

Though with the support and encouragement of my supervisor, I kept trying and also submitted talk proposals for 2023 Cascadia R Conf and posit::conf(2023).

One project/talk, many firsts

In March, things started to look more hopeful as I got my first invitation to speak at an R-Ladies Seattle lightning talk event: R in the Outdoors. This one invitation led to so many of my firsts including my:

• first invitation to speak
• first web scraping project
• first R package
• first in-person talk
• first R-Ladies Seattle event
• first Seattle useR group event

While these all are huge accomplishments to me, I also realize that it’s totally natural because I am so new to the R and coding space. Nevertheless, April 20, 2023 was a huge day for me as this was the first moment since RStudio::con(2022) that I really felt a sense of belonging in the R community.

This was also my first in-person talk of my professional career! I used this as an opportunity to learn new skills through a personal project. I’ve always had an affinity for the Southern Resident Killer Whales in the Salish Sea. The Center for Whale Research does a lot of really fascinating and important work monitoring their population. They post their survey data on their website; each encounter with the orcas is a separate webpage. I’d been curious and intimidated by web scraping so I decided this would make a great case study and personal project.

With the encouragement from new friends I met at the R-Ladies event, we ended up also going to the Seattle useR Group lightning talks meetup afterwards. I spontaneously gave the same presentation there!

Check out the {orcas} package repo and talk materials.

First WADE (attendance & talk)

Outside of the R community and moreso in my capacity as the data scientist at the Washington State Department of Agriculture, I was invited to present at the Washington Association of District Employees (WADE). I presented on the Washington Soil Health Initiative and {WaCSE}.

See the talk materials.

First Master of Science degree

In August, I graduated from Montana State University’s online Land Resources and Environmental Sciences program with a Master of Science. It took me about three years of part-time school with full-time work to complete this degree. I really enjoyed the online aspect of the program as it allowed me to really focus on what was applicable to my job, rather than rote memorization of lots of content I didn’t really need for my day-to-day work. I am a big proponent of learning how to learn in primary and secondary education [thanks dad for teaching me this mentality ☺️], and then using those learning skills to dive deeper into a domain you want to pursue for postsecondary education.

For my professional project (aka the cheaper version of a thesis), I got to learn some JavaScript and Google Earth Engine to model wind-driven soil erosion in Washington State’s Columbia Plateau.

See the repo and my presentation recording.

First Cascadia Conf (attendance & talk)

Given my rejection for Shiny Conf, I definitely didn’t expect to be accepted for Cascadia R Conf or Posit. I used the lessons from my first proposal and made this proposal more unique by focusing less on the Shiny app as a data access tool, and more on the development process and lessons learned from creating our first Shiny app.

See the talk materials.

This was my first time attending Cascadia Conf and I’ve got to say that it is an endearing and enlightening experience. It’s more local and tight-knit than RStudio/Posit conf. I appreciated the smaller size, venue, and one track style of conference. I really enjoyed meeting people I’ve known online in person and making entirely new friends and connections. I loved the experience so much that I volunteered to be on the planning committee for 2024 conf! I’ll be working on the hex logo, paper materials, the witty committee to come up with quirky, fun activities, and helping to update the website.

First Posit Conf talk

Since I already revised the {WaCSE} Shiny talk from the Appsilon Shiny Conf proposal for Cascadia R Conf, I wanted to submit a different topic just in case. So I decided to try a talk about the parameterized soil health Quarto reports. Getting my talk proposal accepted for posit::conf was probably the most shocking news I had for 2023. The call for proposals required an abstract and a 1-minute video pitching the idea for the talk and what I hope the audience will walk away with. I was incredibly intimidated but the amazing Rachael Dempsey wrote a very encouraging and helpful LinkedIn post for those nervous about the video.

I strongly encourage anyone to submit a talk for next year’s conference in Seattle! You never know if you don’t at least try. Posit provides speaker coaching through Articulation, which is so incredibly helpful for learning how to weave a story into your presentation, even with code-based content.

See the talk materials.

General thoughts from my four talks this year

I’ve always been extremely nervous about public speaking. So much anxiety, shaking, sweating, red face, voice cracking, and lightheadedness that I would take propranolol to help. This year I didn’t need it though. I definitely felt nervous and shaky. But not to the same extent. Once I got started presenting, I (for the most part) felt nervous-excited to share whatever I was talking about.

Reflecting on how I felt each talk, I’ve realized that I’m naturally more confident talking about things that I really care about and am professionally and personally invested in. Instead of presenting random research for school projects in my high school and undergraduate classes, I’m presenting projects that I’ve invested dozens of hours in learning, crafting, and perfecting.

First invitation for a workshop

After my posit::conf talk, Arati Krishnamoorthy came up to me to congratulate me on my presentation and ask if I was interested in leading a workshop as a longer version of my talk on parameterized Quarto reports. Of course I said yes, even though I’ve never led a workshop before. It’ll be my first first [workshop] of 2024 on January 18th!

Register for the R-Ladies Washington D.C. Meetup.

So far, I’ve really enjoyed these R focused presentations and teaching. Depending on how the workshop goes, I’m considering applying for The Carpentries Trainer Training Program to better learn how to teach. After all, my husband is an instructional coach (with 5 years of elementary teaching under his belt).

First personal website and blog

Millie Symnns wrote a blog post and gave an excellent posit::conf(2023) talk about the side effects of blogging that inspired me to create my own website and blog. Since RStudio::Conf(2022), I’ve been obsessed with Quarto so the technology behind a website and blog obviously had to be Quarto. It was a blast coming back from Posit Conf and immediately applying what I learned to build my own personal portfolio and website.

First small business - Etsy shop

At Cascadia Conf and Posit Conf, I used my Cricut and heat transfer vinyl to create my own cat and code themed shirts to wear as conversation starters. At both conferences, I made new friends because I was approachable and immediately had two common interests to talk about (R and cats 😻). People asked where I got my shirts and encouraged me to make them available. So to spread the joy and allow others to proudly share/wear their interests, I set up a sole proprietorship, started a small business called The Coding Cats, and launched an Etsy shop found at thecodingcats.etsy.com/!

In 2024, I hope to move from Etsy to a Shopify store that lives on the The Coding Cats tab of my website to avoid the excessive Etsy fees.

First freelance job

Lastly, my first freelance job sort of fell into my lap when a friend referred me to one of their colleagues who was looking for someone to convert their RMarkdown website to Quarto. I picked the brain of my friend to learn about freelancing, listened to some episodes of The Business of Authority podcast, decided on project-based billing rather than hourly billing, consulted with the client, wrote up a proposal, and then began the work.

I actually just finished the next stage of the project earlier today 😀.

While I’m not actively looking for freelance work, I’m happy to entertain the idea and set up a short call to see if I would be a good fit for your project if it involves pretty much anything Quarto.

Last thoughts

I appreciate you sticking through my ramblings (including my future self)!

The year started out with imposter syndrome, so much self-doubt, and one rejection. But with the support from my community, I kept on keeping on. My general theme for the year was perseverance through failures and insecurities to finally get to the realization that I’m exactly where I’m supposed to be. I’m learning as I go, and that’s perfectly okay! My learning directly feeds into my sense of belonging within the R community. This community is so amazing at lifting each other up as we all learn together and support each other. We’re all collectively trying to use the latest technologies and best practices to gain insights from our data and make the world a better place.

Here’s to 2024 being another year of learning, being vulnerable, and lifting each other up!

1 Create a Quarto website

In RStudio, go to File > New Project > New Directory to open the New Project Wizard.

Let’s start with a website. If you’d like to add a blog later on, Samantha Csik wrote a great blog post explaining this process (Csik 2022).

Choose the name of our directory (which will also be the name of our GitHub repository), check the Create a git repository box, then click Create Project.

We should now be in a RStudio project that has index.qmd and _quarto.yml open and some new things in our Files pane:

Our Files pane should have the following:

├── _quarto.yml         # Website configuration file
├── about.qmd           # About page
├── index.qmd           # Landing page
├── my-website.Rproj    # RStudio project config file
└── styles.css          # CSS file for any custom styling

Notice we also have a Git pane with all of these files unstaged and no branches available. This is because we haven’t created a repository on GitHub and connected it with this project yet.

2 Create and connect to GitHub

If you’re following along with Happy Git and GitHub for the useR (Bryan and Hester 2023), we’re using the Existing project, GitHub last workflow.

Thankfully, we can use the usethis package so we don’t have to touch the terminal (yet)! If you haven’t used usethis yet, you’ll need to do the setup described in the package documentation.

Assuming we’ve connected and authenticated our GitHub account in RStudio, we use just two lines of code to create and connect a repository️ to our project 🧙🏼‍♀️.

usethis::use_git()

# ✔ Setting active project to '/Users/jadeyryan/Library/CloudStorage/Dropbox/Mac/Documents/my-website'
# ✔ Adding '.Rhistory', '.Rdata', '.httr-oauth', '.DS_Store', '.quarto' to '.gitignore'
# There are 6 uncommitted files:
# * '_quarto.yml'
# * '.gitignore'
# * 'about.qmd'
# * 'index.qmd'
# * 'my-website.Rproj'
# * 'styles.css'
# Is it ok to commit them?
#
# 1: Negative
# 2: Nope
# 3: Yeah
#
# Selection: 3
# ✔ Adding files
# ✔ Making a commit with message 'Initial commit'

usethis::use_github()

# ℹ Defaulting to 'https' Git protocol
# ✔ Creating GitHub repository 'jadeynryan/my-website'
# ✔ Setting remote 'origin' to 'https://github.com/jadeynryan/my-website.git'
# ✔ Pushing 'main' branch to GitHub and setting 'origin/main' as upstream branch
# ✔ Opening URL 'https://github.com/jadeynryan/my-website'

Our new GitHub repository should open in our browser.

3 Connect and publish to Netlify

In order to use Netlify’s continuous deployment, we need to connect our Git provider to our Netlify account. If you don’t have a Netlify account yet, you can sign up with GitHub.

Once we’re logged into Netlify and connected to our GitHub, we can do the initial publishing with the Quarto CLI. In the terminal, run:

Terminal

quarto publish netlify

If you’re not already logged in to Netlify on your browser, there may be an additional authentication step.

This command rendered our site locally, uploaded all the static files to Netlify, and then deployed and published our new site! The site overview on Netlify should have opened in our browser:

Netlify provided a random site name (stately-chimera-0c91c7) on the netlify.app domain. Also, notice that it says Manual deploys underneath the site link, meaning it was deployed from the quarto publish netlify command in our terminal and not from GitHub.

Click on that link to open our live site!

_publish.yml

- source: project
  netlify:
    - id: b9f73a69-06e7-4de2-9c7b-4f9855b56ba3
      url: 'https://stately-chimera-0c91c7.netlify.app'

Terminal

(base) MacBook-Pro-4:my-website jadeyryan$ quarto publish netlify
? Publish update to: › https://stately-chimera-0c91c7.netlify.app (Netlify - jadey.nicole.ryan@gmail.com)
Rendering for publish:

[1/2] index.qmd
[2/2] about.qmd

[✓] Preparing to publish site
[✓] Uploading files (complete)
[✓] Deploying published site
[✓] Published site: https://stately-chimera-0c91c7.netlify.app

(base) MacBook-Pro-4:my-website jadeyryan$ quarto publish netlify
? Publish update to: › https://my-website24.netlify.app (Netlify - jadey.nicole.ryan@gmail.com)
Rendering for publish:

[1/2] index.qmd
[2/2] about.qmd

[✓] Preparing to publish site
[✓] Uploading files (complete)
[✓] Deploying published site
[✓] Published site: https://my-website24.netlify.app

4 Configure continuous deployment

Now we need to configure several things so Netlify can automatically deploy and publish our site:

• Add Quarto Netlify plugin files
• Freeze code output by setting freeze: auto in _quarto.yml
• Ignore output directory by adding the _site directory to .gitignore
• Link Netlify site to GitHub repository⁶

netlify.toml

[[plugins]]
package = "@quarto/netlify-plugin-quarto"

package.json

{
  "dependencies": {
    "@quarto/netlify-plugin-quarto": "^0.0.5"
  }
}

_quarto.yml

execute:
  freeze: auto

.gitignore

/_site/

5 Branch deploys and deploy previews

As we work on our website styling, content, and features, we probably want to preview our changes without messing up our live site. This is where the Netlify deploy preview system comes into play!

The table below (adapted from Netlify docs) provides a quick comparison of the differences between branch deploys and deploy previews.

6 Lighthouse plugin

Another benefit of Netlify are the integrations with different web tools. The only one I’m using so far is the Google Lighthouse tool, which helps me abide by my accessibility commitment.

Once installed, the Lighthouse plugin audits our site for performance, accessibility, best practices, and SEO at build time. The Lighthouse report gives us scores for each of these four categories.

To enable the plugin, on Netlify > go to Integrations > search for lighthouse > then click Enable.

Netlify will then ask if we’re sure we want to install Lighthouse on our website.

If we click Install, the Lighthouse audit will run the next time we deploy our site.