Each module comes with an assessment. Those are things you need to do that will be graded. Each module has a document, like this one, which describes what the assessments are. Often, there is a good bit of information for the exercises.
If you haven’t done so, please first read through the Assessments page before continuing here.
Get the quiz sheet for this module from the general Assessments page. Fill it in, then submit to the online grading system before the deadline.
For this first module, you have 2 submission attempts. This allows you to get used to the submission system.
Note that the quiz and grading system will only become available once student passwords have been set.
For this module, you are asked to do a project for which you will be using Github, R, RStudio, and Quarto to create the start of a website which will become your portfolio for this class. You’ll write and post a short personal introduction of yourself.
For those of you who are new to Github/R/Quarto, this first project will make you do a lot of things that you are not be familiar with. I know that this will be time-consuming and also might feel a bit intimidating. It’s partly unavoidable and partly on purpose. You need to learn how to quickly get up to speed with all kinds of new tools that come your way. So practicing it is a good idea. You are welcome to draw on any sources for help that you want (online, classmates, instructor, etc.). I’m confident with a bit of trial and error you’ll get it to work.
If you get stuck (quite possible), check the materials listed in the Resources section of the course, or use Google. Also use the discussion boards to ask questions. You may use any method to get help (Google, R4Ds Slack channel, colleagues/friends/relatives with R/Quarto/Markdown experience, etc.). Still, try to do as much as possible yourself. We’ll use all the bits you are learning here repeatedly during this course.
You should have set up with all the tools we need, namely R, RStudio, GitHub and GitKraken (or your preferred Git client).
I made a template for you to get started. Go to this
page. Make sure you are logged into GitHub, then click on
Use this template. Create a new repository, call it
yourname-MADA-portfolio (yourname should
include both your first and last name,
e.g. andreashandel-MADA-portfolio.) Choose public
repository, then create it.
Next, clone the repository (which will be
something like
https://github.com/USERNAME/yourname-MADA-portfolio/) from
Github.com to your local computer (using Gitkraken or whatever
software/method you decided to use). I recommend that you make a folder
somewhere on your computer (e.g., called MADA2023) and place
all class-related repositories (of which this is the first one) into
this folder. Remember that these repositories/folders should
not be synced with some other software (e.g.,
Dropbox).
Once your repository is on your local computer, go into the folder
and click on online_portfolio.Rproj, which should open
RStudio. In the bottom right, you’ll see several files that are part of
your repository/project. We’ll edit a bunch of them shortly. In the top
right panel in RStudio, you should see a Build tab. Click
on it. It should show a Render website button, click it.
You might get complaints about missing packages, if that’s the case,
install them. If everything works well, a local preview of your
soon-to-be new website should open in your browser.
If you got that far, let’s create some content.
For this part of the task, this comprehensive Quarto guide and the Quarto section of the work-in-progress 2nd edition of R for Data Science will likely be useful.
Open index.qmd. This is the main landing page for your
website. Change the text however you want to. What you are writing here
is Markdown, so now would be a good time to check out some of the
Markdown resources and play with them. You will also see at the top of
your R Studio window two buttons Source and
Visual. This allows you to switch between editing Markdown
in plain format, and using a visual editor. It’s a good idea to switch
back and forth to start to learn how certain graphical elements look
like in plain text formatting. You’ll likely be using a mix of visual
and source view a lot.
Next, open aboutme.qmd and write some text introducing
yourself, as follows:
Every time you make changes and want to see how they look, just save your changes and re-load the website in our browser, it should show you any changes.
It is possible to change the looks of your website. Full styling will
require knowledge of CSS and HTML. We won’t get into this. But we’ll
explore a quick way to change the look. Open the
_quarto.yml file. This file defines the menu structure, and
some styling. To change the look, can replace theme with a
different one. Many
themes are available. Try some, see how things change.
Also go ahead and replace the
URL-TO-THIS-REPOSITORY-HERE placeholder text in
_quarto.yml with the actual Github URL of the repository
you just created (e.g. something like
https://github.com/andreashandel/andreashandel-MADA-portfolio).
You can do a lot more styling by for instance editing the
styles.css file. This is not a web design class 😁, we
therefore won’t go into styling further, but feel free to explore on
your own.
Once you are happy with your updates, or if you want to take a break, make sure to push your updates to GitHub. First close RStudio. Then go to the program you use for Github (I will assume that it’s GitKraken. If you use something else the details might vary). In the top right of Gitkraken, there should be a notification about changed files. Click view changes, then Stage all changes. Write a commit message, commit the changes. You should see the main with the computer symbol moved above the one with some random logo. That means your local repository is ahead of the one on github.com. To get them in sync, you click the push button. If things work, the two symbols should now be in the same line.
Sometimes, there might be issues that prevent syncing, e.g., if someone else changed the same files you did. If you are sure your local version is the correct one, you can perform a force push. A force push will overwrite the remote repo with the local repo forcibly. This means that the remote will be updated with any changes that exist on your local computer. If any changes have been made to the code since you began editing (i.e. someone else has made a commit to the repo while you were working on it) they will be destroyed by the force push since they are not on your local repo. For this assignment, you are the only person working on your introduction so it is unlikely you will encounter any issues with force push, but it is good to be aware of the function of the action. Use with care. It’s generally better to resolve merge conflicts.
We want to set things such that your repository can at the same time
become a public website. Github allows you to do that with its Github Pages feature. To
turn on the Github Pages feature, go to your repository on
github.com (e.g. something like
https://github.com/andreashandel/andreashandel-MADA-portfolio).
On the top of the website for your repository, you should see a
Settings button. Click on it and then find the
Pages section. In the Branch section, switch
none to main and folder as /docs.
Click Save.
This should now have turned on your website. You might have gotten a
notice about the location of your new website. If yes, follow the link.
If not, you can get there by going to a URL that has the form
https://username.github.io/yourname-MADA-portfolio/
(e.g. for me, that is
https://andreashandel.github.io/andreashandel-MADA-portfolio/).
It might take a few seconds before the page is available, if you get a
‘not found’ error, wait a bit and try again. If everything works, your
website is now public!
We used the Github pages feature to create the website. You might
have noticed that the files for your new website live on the domain
github.com, while your nice-looking website lives at the
domain github.io. This is how Github Pages work. It take
files from your repository and turns them into a website with a distinct
URL. Those files can either be in the main repository folder or in a
/docs subfolder (our setup). Your website URL and your
repository URL are distinct. All github actions, like pushing, pulling,
cloning, etc. are done with the repository on the
github.com domain. The github.io domain is
only there to display websites.
As an example, this course website is displayed at https://andreashandel.github.io/MADAcourse/ and all the
files that make up the webpage are at (https://github.com/andreashandel/MADAcourse).
Note the text at the bottom of the repository view. That text comes from
the Readme.md file. Speaking of which…
Re-open your project with RStudio. Click to open the README.md file. It only contains a single sentence I placed there. This file will not be part of your website, but it is what people see if they land at your github repository (i.e. the behind-the-scenes location). Add some text to it that points users to the URL for your new website. (You’ve done the reverse above, allowing users to quickly go from your website to your Github repository).
Make any other edits you like.
Once done with edits, remember to re-build/re-render your website
with Quarto (by clicking ‘Render Website’ in the Build tab)
and then committing/pushing your local changes to GitHub (using
Gitkraken or another Git client).
In the future, if you work on repositories like this one (or any others), your workflow should be as follows:
You will be using this workflow a lot.
I wrote a tutorial a while back describing the setup with Github pages. It has some additional information and you can check it out here. Note that this tutorial still used R Markdown instead of Quarto. Some of the information still applies, other parts are different with Quarto.
Using Github pages makes it fairly easy to create websites. I currently host all my course websites in this way. What we created was a fairly basic page. It is easy with Quarto to create other, more full-featured websites. For instance my personal website uses Quarto. If you are interested in such a more full-featured approach, check out this part of the Quarto documentation. You can also find a few more links to other resources here.
The discussion for this module is all about your introductions. For
your original post, simply post the URL to your newly created website
into the introductions slack channel. Do so by
Wednesday.
For your replies, visit some of your classmates websites and leave feedback as a reply to their initial Slack post.
I hope this will allow you to start getting to know each other, even if only virtually.