Converting blogdown to Quarto

Converting blogdown to Quarto

Guide for converting blogdown (Hugo-based) sites to Quarto websites or blogs.

Overview

Key differences:

1. Configuration: config.toml or config.yaml → _quarto.yml
2. Content: Hugo templates → Quarto layouts
3. Shortcodes: Hugo → Quarto shortcodes
4. Themes: Hugo themes → Quarto themes

Quick Start

1. Create Quarto Config

Replace config.toml or config.yaml with _quarto.yml:

project:
  type: website

website:
  title: "My Site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo

2. Rename Files

for f in content/**/*.Rmd; do
  mv "$f" "${f%.Rmd}.qmd"
done

3. Update Front Matter

Blogdown

title: "Post Title"
author: "Author"
date: "2024-01-15"
slug: "post-slug"
categories: ["R"]
tags: ["data"]

Quarto

title: "Post Title"
author: "Author"
date: 2024-01-15
categories:
  - R
  - data

Project Structure

blogdown

config.toml (or config.yaml)
content/
  _index.md
  about.md
  post/
    2024-01-01-first/
      index.Rmd
static/
  images/
themes/
  hugo-theme/
public/

Quarto

_quarto.yml
index.qmd
about.qmd
posts/
  first-post/
    index.qmd
images/
_site/

Configuration Mapping

Basic Site Config

Blogdown (config.yaml)

baseURL: "https://example.com/"
title: "My Site"
theme: "hugo-theme"

params:
  description: "Site description"
  author: "Author Name"

menu:
  main:
    - name: "Home"
      url: "/"
      weight: 1
    - name: "About"
      url: "/about/"
      weight: 2

Quarto (_quarto.yml)

project:
  type: website
  output-dir: _site

website:
  title: "My Site"
  description: "Site description"
  site-url: https://example.com/
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo

author: "Author Name"

The same mapping applies to config.toml — convert TOML keys to the equivalent Quarto YAML.

Blog Setup

Listing Page

Create blog.qmd:

title: "Blog"
listing:
  contents: posts
  type: default
  sort: "date desc"
  categories: true
  feed: true

Post Structure

posts/
  2024-01-15-first-post/
    index.qmd
    images/
      figure1.png
  2024-01-20-second-post/
    index.qmd

Post Front Matter

title: "Post Title"
description: "Brief description for listing"
author: "Author Name"
date: 2024-01-15
categories:
  - R
  - Tutorial
image: images/preview.png
draft: false

Hugo Shortcodes

Figure

Hugo

{{</* figure src="image.png" caption="Caption" */>}}

Quarto

![Caption](image.png)

Tweet

Hugo

{{</* tweet user="username" id="1234567890" */>}}

Quarto (with extension)

{{< tweet username 1234567890 >}}

Install extension: quarto add sellorm/quarto-social-embeds

YouTube

Hugo

{{</* youtube VIDEO_ID */>}}
```

#### Quarto

````markdown
{{< video https://www.youtube.com/embed/VIDEO_ID >}}

Gist

Hugo

{{</* gist user gist_id */>}}

Highlight

Hugo

{{</* highlight r */>}}
code here
{{</* /highlight */>}}
```

#### Quarto

````markdown
```{.r}
code here
```

or

```r
code here
```

Ref/Relref

Hugo

[Link]({{</* ref "other-post.md" */>}})

Quarto

[Link](other-post.qmd)

Taxonomies

blogdown Categories and Tags

categories: ["R", "Data Science"]
tags: ["ggplot2", "visualization"]

Quarto Categories

categories:
  - R
  - Data Science
  - ggplot2
  - visualization

Enable category listing:

# In blog.qmd
listing:
  contents: posts
  categories: true

Static Files

blogdown

Static files in static/ are copied to site root.

Quarto

Put files in project root or use resources:

# _quarto.yml
project:
  resources:
    - images/
    - files/

Themes and Styling

blogdown

Uses Hugo themes from themes/ directory.

Quarto

Use built-in themes or custom SCSS:

format:
  html:
    theme:
      - cosmo
      - custom.scss

Custom SCSS

// custom.scss
$body-bg: #ffffff;
$body-color: #333333;
$link-color: #0066cc;

// Custom rules
.quarto-title {
  font-size: 2.5rem;
}

RSS Feed

blogdown

Hugo generates RSS automatically.

Quarto

Enable in listing:

• blog.qmd

  ---
  listing:
    feed: true
  ---
  

Or in _quarto.yml:

website:
  site-url: https://example.com

listing:
  feed:
    title: "My Blog"
    description: "Blog description"

Comments

Quarto

In _quarto.yml:

website:
  comments:
    giscus:
      repo: username/repo
      category: "Comments"

Or per-post:

comments:
  giscus:
    repo: username/repo

Syntax Highlighting

blogdown

Configured in Hugo config or theme.

Quarto

format:
  html:
    highlight-style: github
    code-line-numbers: true
    code-fold: true

Draft Posts

blogdown

draft: true

Quarto

Same syntax:

draft: true

Render drafts with:

quarto render --profile drafts

With profile config:

# _quarto-drafts.yml
execute:
  echo: true

website:
  drafts: true

Deployment

Netlify

# netlify.toml
[build]
  command = "quarto render"
  publish = "_site"

GitHub Pages

# .github/workflows/publish.yml
name: Publish

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: quarto-dev/quarto-actions/setup@v2
      - run: quarto render
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

Common Issues

Missing Shortcodes

Install Quarto extensions for missing functionality.

Broken Internal Links

Update .md and .Rmd extensions to .qmd.

Theme Differences

Quarto themes differ from Hugo themes; expect visual changes.

Build Errors

Check for Hugo-specific template syntax in content files.

Resources

• Quarto Websites
• Quarto Blogs
• Quarto Themes