| 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
See the [about page](about.qmd) for details.
# WRONG
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
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
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
---
title: "Blog"
listing:
contents: posts
sort: "date desc"
type: default
categories: true
---
Listing Types
listing:
type: default
contents: posts
listing:
type: grid
grid-columns: 3
contents: posts
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
feed: true
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
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:
website:
title: "My Blog"
site-url: https://myblog.com
listing:
feed:
items: 20
type: full
title: "My Blog Feed"
categories: [python, data-science]
Search
website:
search:
location: navbar
type: overlay
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
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
Quarto Pub
quarto publish quarto-pub
Best Practices
- Internal links: Link to
.qmd files, not .html files
- Blog dates: Use fixed dates, not
today or last-modified (affects listing order)
- Post structure: Each post in its own subdirectory with
index.qmd and local images
- Freeze: Use
freeze: true in posts/_metadata.yml to avoid re-executing old posts
- Version control: Gitignore
_site/, commit _freeze/ if using freeze
- 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 configurationreferences/listings-and-feeds.md — Listing types, filtering, sorting, categories, RSS feed configuration, and custom templates
