Quarto Blog Tutorial 1: Initializing using RStudio

Creating a Quarto blog from scratch using RStudio. – A visual guide.

Initializing a Quarto blog, explaining the generated key files and the starting content of the Quarto project file _quarto.yml and the blog homepage file index.qmd.

blog
quarto
rstudio
tutorial
Author

Peter Baumgartner

Published

July 22, 2024

Modified

July 22, 2024

Image by Mine Çetinkaya-Rundel from Get Started with Quarto - A video to jumpstart your Quarto journey. Featuring a new video for getting started with Quarto using R and RStudio.

Image by Mine Çetinkaya-Rundel from Get Started with Quarto - A video to jumpstart your Quarto journey. Featuring a new video for getting started with Quarto using R and RStudio.

Initializing a Quarto Blog

There are several ways to start a new Quarto blog. I will use a menu driven approach using RStudio. For the following workflow you should have installed RStudio and have some knowledge how to use it.

I will not explain everything related to creating a new Quarto blog; instead, I will focus on my choices to initialize the blog.

I am using

  • R version 4.4.1 (2024-06-14)
  • Quarto version 1.5.54

New Project…

Inside RStudio, use the New Project… command and select New Directory and then Quarto Blog.

RStudio new project wizard window with three options reading from the top: New Directory - Start a project in a brand new working directory; Existing Directory - Associate a project with an existing working directory; Version Control - Checkout a project from a version control repository.
Figure 1: RStudio new project wizard window (Screenshot): Choose ‘New Directory’ to start an new project from scratch.
The Project Type dialog window lists the choices for new project. The first seven options are visible: New Project, R Package, Shiny Application, Quarto Project, Quarto Website, Quarto Blog, Quarto Book. (From top to the bottom. Top left is a button 'Back' for returning to the previous dialog window. Bottom right is a 'Cancel' button to stop the initialization process.
Figure 2: RStudio project type window (Screenshot): Choose ‘Quarto Blog’ to initialize a blog project
The 'Create quarto Blog' dialog window requires a file name for the directory of the repository, titled 'Directory name', a directory where the project will be created, titled 'create project as subdirectory of:' with a 'Browse' button to the right, a drop down menu selecting 'Knitr' as the current option, titled 'Engine', three lines of check boxes, titled 'Create a git repository' (checked), 'Use renv with this project' and 'Use visual markdown editor'. The last option is followed by a question sign to get more information about the choice of a visual markdown editor. Top left in the dialog window is a button 'Back' for returning to the previous dialog window. Bottom left is a check box 'Open in a new session', Bottom right are a 'Create Project' button followed by a 'Cancel' button for stopping the initialization process.
Figure 3: RStudio Create Quarto Blog window (Screenshot): Fill the input fields with the appropriate data
  • I am using {knitr} as the engine.
  • The {renv} package is for creating reproducible environments for R projects. I will not use it as I have no experience with this complex package, and reproducibility is not an issue for my private blog (at least, I think so at the moment).
  • Selecting “Use visual markdown editor” is not important, as this option is for all .qmd files in RStudio always available. I think that this option only controls the default behavior whenever a new file for a post is created.

Key Files

Clicking the “Create Project” button generates different key files and opens the _quarto.yml file in the RStudio editor window.

At the top of the screenshot there are six tabs. From left to the right: 'Files', 'Plots', 'Packages', 'Help', 'Viewer', 'Presentation' with the 'Files' tab active. Under the tabs are several buttons. From left to the right: 'New Folder', 'New Blank File', 'Delete', 'Rename' and a drop down menu 'More'. Under these buttons is the full path to the active directory 'Home>Documents>Meine-Repos>quarto-pb-blog' where each subdirectory is an active link. Under this line starts the file listing with 'Name', 'Size' and 'Modified' columns. Each line of file names starts with an (unchecked) check box, and an appropriate icon. From top to bottom: _freeze, _quarto.yml, _site, .git, .gitignore, .quarto, .Rhistory, .Rproj.use, about.qmd, index.qmd, posts, profile.jpg, quarto-pb-blog.Rproj, style.css.
Figure 4: RStudio file listing window (Screenshot): Choose ‘New Directory’ to start an new project from scratch.

If you can’t see all five files starting with a dot (so-called dotfiles) in your installation, go to the drop-down menu ‘More’ and check the last option ‘Show Hidden Files’.

Here’s a summary of the key files created within the starter blog project:

Table 1: Key files after initializing a Quarto blog
File Description
_quarto.yml Quarto project file.
index.qmd Blog home page.
about.qmd Blog about page.
posts/ Directory containing posts
posts/_metadata.yml Shared options for posts
styles.css Custom CSS for website

Content of the Quarto Project File

Here is the content of _quarto.yml:

_quarto.yml
project:
  type: website

website:
  title: "quarto-pb-blog"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: twitter
        href: https://twitter.com
format:
  html:
    theme: cosmo
    css: styles.css

Content of the Blog Home Page

Here is the content of index.qmd:

index.qmd
title: "quarto-pb-blog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---

Render Blog

The screenshot shows a part of the RStudio source code window with two file tabs 'index.qmd' (active) and '_quarto.yml'. Below is a line of partly disabled buttons where the focus is on the 'Render' button that has below a tip tool saying 'Render the current document (SHIFT-CMD-K)'
Figure 5: Source code of the blog home page ‘index.qmd’-file within RStudio window (Screenshot)

You can control via Tools->Global Options…->R Markdown->Show output preview in… whether the rendered result appears in the browser window or in the viewer pane. Generally, I use the “Window” option because it gives me a better view of the real setting.

The webpage lists two dummy blog post with three columns: From left to the right: Date and author; blog post title, category buttons and a short description; a small image. On the right margin is a list of categories displayed with their frequency in parenthesis. The title header of the website consists of two lines: Left top: Name of the Quarto blog so far 'quarto-pb-blog', Right top: 'About' followed by icons for GitHub, Twitter and search engine.
Figure 6: Website of the newly created Quarto blog (Screenshot): 
RStudio console output
==> quarto preview index.qmd --to html --no-watch-inputs --no-browse

pandoc to: html
  output-file: index.html
  standalone: true
  title-prefix: quarto-pb-blog
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png
  css:
    - styles.css
  
metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  theme: cosmo
  title: quarto-pb-blog
  listing:
    contents: posts
    sort: date desc
    type: default
    categories: true
    sort-ui: false
    filter-ui: false
  page-layout: full
  title-block-banner: true
  
WARN: Unable to read listing item description from posts/post-with-code/index.html
WARN: Unable to read listing item description from posts/welcome/index.html
WARN: Unable to read listing preview image from posts/welcome/index.html
Output created: _site/index.html

Preparing to preview
[1/4] posts/post-with-code/index.qmd
R version 4.4.1 (2024-06-14)

processing file: index.qmd
                                                                                                            
output file: index.knit.md

[2/4] posts/welcome/index.qmd
[3/4] about.qmd
[4/4] index.qmd

Watching files for changes
Browse at http://localhost:5146/
GET: /

As you can see in the above console output I got three warnings:

  • Unable to read listing item description from posts/post-with-code/index.html
  • Unable to read listing item description from posts/welcome/index.html
  • Unable to read listing preview image from posts/welcome/index.html

These warnings are prompted by the fact that we need to render the complete blog with SHIFT-CMD-B or by clicking “Render Website” after choosing the “Build” button on the upper right RStudio pane. I will explain render strategies in a later post.

Summary

This is the end of the initialization process. In later blog posts I will add more functionality and style the web page it to get a more attractive appearance of the Quarto blog.

Back to top