Let’s build a blog with Quarto

Quarto blogs are a convenient way to publish listings of documents.
Try it out!

Follow along in the exercises:

  • rstd.io/quarto-blog-exercise-repo
  • Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

Websites share:

Blogs are a specific type of website:

Getting started with a new Quarto blog

Create a new blog in the terminal:

quarto create-project my-new-blog --type website:blog

If you are using RStudio, you can use the New Project command to create a Quarto Blog:

Preview and render your blog

  • To preview the site, use the preview command in the terminal:
quarto preview mysite

The development server will automatically re-render input files whenever they change.

  • To render the site, use the render command in the terminal:
quarto render mysite

Make sure to render before pushing up changes!

If you are using RStudio, you can do this in the IDE’s Build tab. Be sure to check “Render on Save”:



Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

  • Create a new blog using the RStudio wizard and preview the site.
  • Or, open the RStudio Cloud project and preview the site.

Quarto blog files

When you create a new blog, these files will be automatically populated in your directory:

Creating project at myblog:
  - Created _quarto.yml
  - Created index.qmd
  - Created posts/welcome/index.qmd
  - Created posts/post-with-code/index.qmd
  - Created about.qmd
  - Created styles.css
  - Created posts/_metadata.yml
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

index.qmd: Blog home page

The index.qmd file in your home directory will be the landing page for your site.

  • When creating a new blog, it will default to the listing page for the documents in the posts directory.
  • If you prefer that the About page is your landing page, you can rename your index.qmd to posts.qmd and about.qmd to index.qmd.

Default listing page

---
title: "my-new-blog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---

Let’s go through each line:

title

The title of your listing page.

listing

listings generates the contents of a page (or region of a page) from a set of Quarto documents or other custom data.

contents

contents control what documents are included in the listing by specifying a set of input files.

  • contents: posts contains documents from the posts/ folder.

sort

sort controls the order of the listing.

  sort: "date desc"
  sort: "date asc"
  sort: "title asc"
  sort:
    - date desc
    - title desc

type

type controls how the listings look.

Three default styles:

type: grid

type: table

type: default

You can write custom listings in Embedded JavaScript templating (EJS).

Tooting my own horn:

Listing made with EJS on ivelasq.rbind.io

categories

categories display the categories for your posts. The categories are read from the YAML of the documents included in the listing.

categories: true

Categories list on the right-hand side of a listing

categories: numbered

Categories list on the right-hand side of a listing with numbers on the side denoting the count

categories: unnumbered

Categories list on the right-hand side of a listing without numbers

categories: cloud

Categories list on the right-hand side of a listing with each category in a size corresponding to how many posts are using that category

sort-ui

sort-ui provides a sorting box for readers.

sort-ui: true

UI for sorting blog posts on the left-hand side of a listing page

filter-ui

filter-ui provides a filtering box for readers.

filter-ui: true

UI for filtering blog posts on the right-hand side of a listing page

page-layout

page-layout controls the layout used.

title-block-banner

title-block-banner positions a formatted title block at the start of the article.

Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

In the index.qmd file of your Quarto blog:

  • Change the title of your listing page.
  • Choose another listing type.
  • Change the sort option to date asc.
  • What happens when you change filter-ui to true?

about.qmd: Blog about page

The about.qmd document includes additional information on the blog and its author.

Default about page

---
title: "About"
image: profile.jpg
about:
  template: jolla
  links:
    - icon: twitter
      text: Twitter
      href: https://twitter.com
    - icon: linkedin
      text: LinkedIn
      href: https://linkedin.com
    - icon: github
      text: Github
      href: https://github.com

---

Let’s go through each line:

title

The title of your About page.

image

The image for the About page.

about

The option to create an About page.

template

template controls how the About page looks.

Five built-in templates:

template: jolla

template: trestles

template: solana

template: marquee

template: broadside

- icon

One of the standard Bootstrap 5 icons.

text

Text to display for navigation item.

href

Link to file contained with the project or an external URL.

Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

In the about.qmd file of your Quarto blog:

  • Change the title of the page.
  • Change the template to marquee.
  • Update the links to your profiles pages.

_quarto.yml: Quarto project file

The _quarto.yml file is the configuration file for your website.

project:
  type: website

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

editor: visual

Let’s go through each line:

project

The type of project (vs book, etc.).

title

The title of your blog.

- about.qmd

The file to be linked. The title will default to the document’s title.

- icon

The icon to be shown.

href

The link associated with the icon.

There are other options available for the top level navigation. For example, if we want to change the background to orange, we could add:

  navbar:
    background: "#C45508"

Make sure that you are indenting correctly!

There are also other options for the individual navigation items. For example, if we want to add text to the right side:

  navbar:
    right:
      - text: "my name here"

Quarto top navigation documentation

Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

In the _quarto.yml file of your Quarto blog:

  • Change the background to a different color.
  • Add another hyperlink in the navigation bar.
  • Add your name to the left side of the top navigation bar.

Themes

This section adds your theme.

The 25 Bootswatch theme names:

  • default
  • cerulean
  • cosmo
  • cyborg
  • darkly
  • flatly
  • journal
  • litera
  • lumen
  • lux
  • materia
  • minty
  • morph
  • pulse
  • quartz
  • sandstone
  • simplex
  • sketchy
  • slate
  • solar
  • spacelab
  • superhero
  • united
  • vapor
  • yeti
  • zephyr
format:
  html:
    theme: cosmo
    css: styles.css

Blogs can use any of the 25 Bootswatch themes included with Quarto, or you can create your own theme.

format:
  html:
    theme: cosmo
    css: styles.css

Website in cosmo theme

format:
  html:
    theme: darkly
    css: styles.css

Website in darkly theme

format:
  html:
    theme: sketchy
    css: styles.css

Website in sketchy theme

Dark themes

Quarto websites also support light and dark themes. A toggle will allow your reader to select the desired appearance.

Specify under theme:

format:
  html:
    theme: 
      light: cosmo
      dark: darkly

Syntax highlighting

You can also change the syntax highlighting for your code blocks. Run the below to see all the options:

quarto pandoc --list-highlight-languages

You can use YAML intelligence to find your perfect highlight style too!

Specify the syntax highlighting style by specifying highlight-style under theme:

format:
  html:
    theme: cosmo
    css: styles.scss
    highlight-style: espresso

Code in espresso highlighting

format:
  html:
    theme: cosmo
    css: styles.scss
    highlight-style: eiffel

Code in eiffel highlighting

format:
  html:
    theme: cosmo
    css: styles.scss
    highlight-style: zenburn

Code in zenburn highlighting

Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

In the _quarto.yml file of your Quarto blog:

  • Change to another Bootswatch theme.
  • Add a dark theme with another Bootswatch theme.
  • Change the syntax highlighting to espresso.

styles.css: Custom CSS for website

This is the CSS stylesheet for your website.

  • Can also use .scss file.
Try it out!

rstd.io/quarto-blog-exercise-repo
Launch RStudio Cloud rstd.io/quarto-blog-exercise-cloud

In the styles.css file of your Quarto blog:

  • Add:
@import url('https://fonts.googleapis.com/css2?family=Pacifico&family=Pacifico&display=swap');

h1.title {
  font-family: "Pacifico";
  font-size: 30px;
}

And preview your blog.

You have built a blog with Quarto! 🎉