ASSIGNMENT 2

GitHub

Adding a Quarto project to GitHub
Assignment
Project
Quarto
Portfolio
GitHub
Version Control
Author

Barrie Robison

Published

August 30, 2024

SUMMARY

The basic idea of this assignment is to set up a GitHub repository that will serve as an experimental portfolio, and then create a practice communication element inside the portfolio. Its gonna be fun! Or at least educational…

ASSIGNMENT

This assignment has two parts. The first part is technical. We’ll set up a Quarto Blog project as a new repository in your GitHub account. Then you’ll be a Blogger! Prestigious! The second part should be more fun. We are going to create your first Blog post using a practice / dummy / simple quarto document. Ideally this would be your .qmd file from Assigment 1.

PART 1 TECHNICAL SORCERY

1A - Create your BLOG project.

Hopefully by now you have created / dusted off / logged in to your GitHub account. Go ahead and log in to your account on the web and leave it open in a tab in your browser. There is a really great video about the next few steps (also linked below in RESORUCES) from Posit, but I’m giving you the condensed version here.

  1. Fire up RStudio.
  2. Go to File->New Project and then select NEW DIRECTORY.
  3. Now select QUARTO BLOG.
  4. You are going to create the project in a new working directory. It is best practice to put this in a sensible directory structure on your local hard drive where your other GitHub repositories also live. Here is what mine looks like:

Note: I currently have my GitHub directory in my Documents folder, which appears to sync with some kind of Apple Cloud thingy. I think this is causing some issues that I haven’t fully dealt with. I don’t recommend putting your local directory on any kind of shared or networked drive.

  1. I suggest making the directory name something informative, like BCB521Portfolio, but hey… If you want to call your repository HasturBoxerShorts I won’t stop you.

  2. Most of you will select Knitr as your Engine, but if you were a Python coder you might select Jupyter.

  3. Check Create a git repository. At some point, you might be asked about making the repository private. Uncheck that box and make it public. Otherwise the website functionality of GitHub pages won’t work. The other boxes are optional and we can talk more about them later.

  4. Click CREATE PROJECT.

Now you’ve got a BLOG template all set up! Ha Ha! Onward to Internet Fame!

1B - Make the BLOG about you.

We won’t spend a ton of time here, because this will be an ongoing process. You’ll go and watch all those cool videos and tutorials this weekend to figure this out. But lets do a couple things.

  1. Maybe you should modify the about.qmd file so that your name is in there somewhere.
  2. Maybe you should modify the index.qmd file with a better title in the YAML header.
  3. Maybe you should navigate to the posts folder, open the Welcome to my blog folder, open index.qmd from that directory, and add a sentence or two.

PART 2 INTERNET FAME

2A - Make Assignment 1 a BLOG post.

  1. Navigate to the posts folder, open the post with code folder, and open index.qmd.
  2. Replace ALL of the content of index.qmd with the most recent version of your .qmd file from ASSIGNMENT 1. Keep the file name index.qmd or rename it to something else. Save that file!
  3. Move any data files pertaining to Assignment 1 to the post with code folder.
  4. Render the index.qmd file (or whatever you renamed it) from this folder. Hopefully it worked!

2B - Render the BLOG as a website.

  1. IMPORTANT Open your _quarto.yml file and add output-dir: docs under project:

The indentations matter here.

  1. Save all the files you’ve modified.
  2. Go to the BUILD tab in the (probably) top right section of RStudio.
  3. Click RENDER WEBSITE.
  4. Click through your new Blog and see how it works!

2C - Push to GitHub.

There are quite a few ways to do this part. I’m going to use GitHub Desktop, but those videos will show you other ways.

  1. Go to GitHub Desktop.
  2. You may have to add your repository to GitHub Desktop. On my Mac I use File -> Add Local Repository and then point to the local directory.
  3. Type some text in the summary box.
  4. Click COMMIT TO MASTER.
  5. Click PUSH ORIGIN.
  6. Go to your GitHub in your browser. You should see your new repository! Yay!

2D - Make it a website with GitHub pages.

  1. In your browser, click on your repository.
  2. Go to SETTINGS.
  3. Select PAGES.
  4. Set the SOURCE option to Deploy from a branch.
  5. Set the BRANCH to master and the directory to docs
  6. Deploy that stuff and wait. Then visit your site!

RESOURCES

A YouTube Video from Posit on Building your Data Science Portfolio

Quarto’s BLOG Documentation

A YouTube Video from Posit on Building a BLOG with Quarto