Blogging with Quarto
Last knit: 2023-08-04
I often assign “blogging” as an optional way for students to engage in course material. There are lots of ways to get a blog up and running on the internet, and my preference is to suggest that students adopt and learn R Markdown and RStudio for their blogging workflow. Many of my students are unfamiliar with computer programming in R, so learning how to blog with R can be a useful gateway to computational skills.
R Studio now comes packaged with Quarto, which provides yet another blogging workflow. This post is intended for my students as a quick guide to setting up a quarto blog.
Overview
Here’s an outline of what is in store. You will need to download some free software to your computer and make a free account on Github.com. After the software is downloaded you will be able to open a blogging template (with all the files you need to get started), edit and make new posts, and preview the blog on your computer. Finally, we’ll discuss how to share the blog on the internet. At the end, you should be able to make your own new blog posts using this workflow. Last, you do not need to know how to program in R to do this.
I intend to make a video overview and put it here, but the text-based instructions should be enough to get you started as well…here’s the video.
Get the software you need
- Sign up for a free account at https://github.com. This a website for sharing open-source software, but it can also be used to serve your blog as a website for free.
- Download Github Desktop and install it on your machine. This should install the version control software git on your system, and you can use Github Desktop to easily push your blog from your local computer so that it can be viewed on Github.com.
- Download R and install it on your machine. R is a programming language capable of many things, and it needs to be on your machine before you can run R Studio.
- Download R Studio Desktop and install it on your machine. R Studio is called an “IDE” or integrated development environment, that you can use to write your blog with quarto.
Make a quarto blog project
If you already have R Studio on your machine, then make sure you have the latest version, which includes quarto.
- Open up R studio.
- Choose File -> New Project
- You should see a pop-up menu
- Choose “New Directory”
- Choose “Quarto Blog” for project type
- The blog files will be stored in a new folder, give your new folder a simple name (no spaces). This will also be the name for your github repository later on. Make sure “Create a git repository” is clicked. Then press create project.
Compile your blog
If everything went smoothly, then you should be looking at a new R Studio project with the source code for you blog. I named my project “cognitionBlog”, and this is what I am looking at after pressing “Create Project”.
This is an R Studio project with a template for making a blog. As you learn more about quarto, you will be able to modify and customize the blog to your own liking. Quarto is a very powerful document creation system that can be used to make websites, blogs, slide decks, books, and more; and, you can find more info about it here: https://quarto.org.
For the purpose of this tutorial, I’ll try to keep things as simple as possible so you can start blogging.
You should be able to see a preview of what the blog will look like right away.
- Go to the “build” tab in the top right hand corner, and press “Render website”.
- You may see a preview of the website in the R Studio browser window, and you can click this little button to preview the blog in your default browser.
Writing your own posts
I recommend learning to blog with quarto by opening and modifying the template files.
You can see all of the files in your project by clicking on the files tab:
The default quarto blog is a bare-bones website with a list of blog posts and an about page. You can change the title of the blog in “index.qmd”, and add more info to the about page by writing new text in “about.qmd”. But, let’s focus on making a new post.
First, navigate into the “posts” folder. The template contains two existing posts. Each post is in its own folder.
To make a new post, you can “copy” an existing folder for a post and give it a new name.
I named my new post “my-new-post”, and now I can see it listed as a folder beside the original two from the template.
Let’s click into the folder and edit the “index.qmd” file. Here are the files inside the folder:
Clicking on “index.qmd” should open the file in the R studio text editor (on the left):
I edited this file and gave it a new title, new author, etc. Then I deleted the text at the bottom and wrote my own first blog post.
Now, if I render the website again (from the build tab), my new post is automatically added to the list of posts (they are listed in order by date).
You could now be off to the races. To further customize, delete the template posts you don’t want and replace them with your own. At this point your blog is only on your local computer. If you want to share it on the internet, then follow the next steps to share your blog using Github.com.
Write more and push to publish
Once you have everything set up you should be able to:
- Make new posts by copying an existing one.
- Publish them by rendering the website on your computer, and pushing your changes to Github.com
And, that’s it. Happy blogging.