quarto-websites

name

quarto-websites

description

Create and edit Quarto website and blog projects. Use when the user asks to "create a Quarto website", "build a blog with Quarto", "set up a Quarto site", "add a blog post", "configure website navigation", "set up a navbar", "add a sidebar", "create a listing page", "add RSS feed", "deploy my Quarto site", or needs help with website _quarto.yml configuration, navigation, listings, blog posts, categories, search, or site deployment.

Quarto Website and Blog Projects

Create multi-page websites and blogs with navigation, search, listings, and blog features. Websites use a _quarto.yml configuration file and render to a _site/ directory.

Critical Rule: Relative Paths

All links to images, stylesheets, and other resources MUST use paths relative to each page's location or the project root. For internal page links, link to the .qmd source file (not the .html output).

# CORRECT
![](images/photo.png)
See the [about page](about.qmd) for details.

# WRONG
![](/absolute/path/to/site/images/photo.png)
See the [about page](about.html)

Project Setup

Create a New Website

quarto create project website my-site
cd my-site
quarto preview

Create a Blog

quarto create project blog my-blog
cd my-blog
quarto preview

Minimal _quarto.yml

project:
  type: website

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

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

Directory Structure

my-site/
├── _quarto.yml
├── index.qmd            # Homepage
├── about.qmd            # About page
├── styles.css           # Custom styles
├── posts/               # Blog posts (if blog)
│   ├── _metadata.yml    # Shared post options
│   ├── first-post/
│   │   └── index.qmd
│   └── second-post/
│       ├── index.qmd
│       └── images/
├── images/              # Site-wide images
├── _site/               # Output (gitignore this)
└── .gitignore

Navigation

Navbar

website:
  navbar:
    background: primary
    search: true
    logo: images/logo.png
    left:
      - href: index.qmd
        text: Home
      - text: "Topics"
        menu:
          - href: topic-a.qmd
            text: "Topic A"
          - href: topic-b.qmd
            text: "Topic B"
    right:
      - icon: github
        href: https://github.com/user/repo
      - icon: rss
        href: index.xml
    pinned: true
    collapse-below: lg

Sidebar

website:
  sidebar:
    style: docked          # or "floating"
    search: true
    collapse-level: 2
    contents:
      - text: "Introduction"
        href: intro.qmd
      - section: "Tutorials"
        href: tutorials/index.qmd
        contents:
          - tutorials/getting-started.qmd
          - tutorials/advanced.qmd
      - section: "Reference"
        contents:
          - reference/api.qmd
          - reference/config.qmd

Auto-Generated Sidebar

website:
  sidebar:
    contents: auto    # Generates from filesystem structure

Hybrid: Navbar + Multiple Sidebars

website:
  navbar:
    left:
      - text: "Guide"
        href: guide/index.qmd
      - text: "Reference"
        href: reference/index.qmd

  sidebar:
    - title: "Guide"
      contents:
        - guide/index.qmd
        - guide/getting-started.qmd
    - title: "Reference"
      contents:
        - reference/index.qmd
        - reference/api.qmd

Additional Navigation

website:
  page-navigation: true
  back-to-top-navigation: true
  bread-crumbs: true
  reader-mode: true
  page-footer:
    left: "Copyright 2026"
    right:
      - icon: github
        href: https://github.com/user/repo

Listing Pages

Listing pages automatically display collections of documents.

Basic Listing

# In index.qmd frontmatter:
---
title: "Blog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
---

Listing Types

# Blog-style cards
listing:
  type: default
  contents: posts

# Card grid
listing:
  type: grid
  grid-columns: 3
  contents: posts

# Tabular
listing:
  type: table
  contents: posts
  fields: [date, title, author, categories]

Listing Configuration

listing:
  contents: posts
  sort: "date desc"
  type: grid
  grid-columns: 3
  categories: numbered     # or true, unnumbered, cloud
  feed: true               # Generate RSS
  page-size: 12
  filter-ui: true
  sort-ui: true
  date-format: "MMM D, YYYY"
  max-description-length: 175
  image-height: 200px
  image-placeholder: images/default.png

Multiple Listings on One Page

listing:
  - id: recent-posts
    contents: posts
    sort: "date desc"
    max-items: 5
    type: default
  - id: tutorials
    contents: tutorials
    type: grid

Place them in the page body:

## Recent Posts

::: {#recent-posts}
:::

## Tutorials

::: {#tutorials}
:::

Blog Posts

Post Frontmatter

---
title: "Post Title"
description: "Brief description for listings and social cards"
author: "Author Name"
date: "2026-03-15"
date-modified: "2026-03-20"
categories: [analysis, python]
image: images/thumbnail.png
draft: false
---

Draft Posts

draft: true   # Visible in preview, hidden when rendered

Shared Post Options

Create posts/_metadata.yml for settings shared across all posts:

freeze: true
execute:
  echo: false
  warning: false

RSS Feed

Enable in the listing page and provide site URL:

# _quarto.yml
website:
  title: "My Blog"
  site-url: https://myblog.com

# index.qmd
listing:
  feed:
    items: 20
    type: full
    title: "My Blog Feed"
    categories: [python, data-science]

Search

website:
  search:
    location: navbar    # or sidebar
    type: overlay       # or textbox
    copy-button: true

Themes

25 built-in Bootstrap themes: 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:
      light: flatly
      dark: darkly
    css: custom.css

About Pages

---
title: "About"
image: profile.jpg
about:
  template: jolla     # or solana, trestles, broadside, marquee
  links:
    - icon: twitter
      text: Twitter
      href: https://twitter.com/user
    - icon: github
      text: GitHub
      href: https://github.com/user
---

Social Metadata and Analytics

website:
  site-url: https://mysite.com
  google-analytics: "G-XXXXXXXXXX"
  open-graph: true
  twitter-card:
    creator: "@username"
    site: "@sitename"

Deployment

GitHub Pages

quarto publish gh-pages

Netlify

quarto render
# Deploy _site/ directory

Quarto Pub

quarto publish quarto-pub

Best Practices

1. Internal links: Link to .qmd files, not .html files
2. Blog dates: Use fixed dates, not today or last-modified (affects listing order)
3. Post structure: Each post in its own subdirectory with index.qmd and local images
4. Freeze: Use freeze: true in posts/_metadata.yml to avoid re-executing old posts
5. Version control: Gitignore _site/, commit _freeze/ if using freeze
6. Images: Keep post-specific images in the post directory, shared images in a root images/

Resources

• references/navigation-config.md — Complete navbar, sidebar, hybrid layout, footer, and search configuration
• references/listings-and-feeds.md — Listing types, filtering, sorting, categories, RSS feed configuration, and custom templates