Reference

Every option the atelier project type contributes, and the extension keys it reads.

This page lists what project.type: atelier sets on your behalf and the keys you can set yourself.

Extension options

These go under extensions.atelier in _quarto.yml. Each icon and manifest tag is emitted only when its key is set, while theme-color also follows the brand.

Keys under extensions.atelier.
Option Description
site-url Base URL for <meta property="og:url">. Anchor it to website.site-url.
icon Path to an SVG icon, emitted as rel="icon" with type="image/svg+xml".
apple-touch-icon Path to a 180x180 PNG, emitted as rel="apple-touch-icon".
manifest Path to a web app manifest, emitted as rel="manifest".
theme-color Browser UI tint (Safari toolbar, Android address bar, installed web app title bar), one colour per scheme, each emitted with a prefers-color-scheme media query. Each scheme falls back to color.background of the _brand.yml for that mode, which is the page background of the matching bundle; set a scheme only to override it.

Paths are relative to the site root. Quarto’s website resource resolver prefixes each page’s offset to the project root, so the same value resolves at the root, from a subdirectory such as this page, and from the 404 page.

website:
  site-url: &site-url https://example.com/my-project
extensions:
  atelier:
    site-url: *site-url
    icon: assets/icons/icon.svg
    apple-touch-icon: assets/icons/apple-touch-icon.png
    manifest: site.webmanifest
    theme-color:
      light: "#F5F7FA"
      dark: "#0B1220"

The anchor is needed because Quarto keeps the website block out of the metadata it hands to Lua filters.

Website defaults

The project type sets these under website, and any of them can be overridden in your own _quarto.yml.

Keys the project type sets under website.
Key Value
repo-actions [edit, issue]
repo-link-target, repo-link-rel _blank, noopener noreferrer
open-graph.locale en_GB, matching the format’s lang
twitter-card.card-style summary_large_image
page-navigation, back-to-top-navigation true
llms-txt true
search Overlay search in the navbar
navbar, page-footer On, with the footer border on

It also sets project.output-dir to _site.

Neither bar sets background or foreground: the chrome palette drives both, and $atelier-chrome decides whether it follows the colour scheme or is pinned to light or dark.

A website.sidebar of your own is styled rather than configured: a style: docked sidebar is painted from the --atelier-sidebar-* tokens, which default to the navbar ones, while a style: floating sidebar takes the chrome background and foreground alone. This site sets navbar: false and gives the docked sidebar the navigation and the search; --profile navbar renders the same pages with the navbar instead.

Format defaults

The project type sets format: atelier-html. Configure it by that name: declaring format: html replaces it rather than configuring it.

Keys the project type sets on atelier-html.
Key Value
lang en-GB
date-format dddd[, the] Do [of] MMMM, YYYY
theme The chrome palette, brand, and the Atelier stylesheet, light and dark
syntax-highlighting github-light and github-dark
toc, toc-depth true, 3
anchor-sections true
code-copy, code-overflow true, wrap
code-link false
link-external-newwindow true
respect-user-color-scheme true
canonical-url true
grid 300px sidebar, 1000px body, 300px margin

It also bundles six scripts into every page: a skip link before the body, and after it the current year, the external-link marks, the ordinal dates, the accessibility fixes, and the navbar tooltips. Replacing the format with html drops all six, which is what the id="navbar-tooltips" check on the home page looks for.

Page keys

Front matter keys the project type reads.
Key Effect
description Fills <meta name="description"> and Quarto’s og:description.
subtitle Used for the description tags when description is absent.
description-meta Used as written, in preference to both.
canonical-url: false Drops the canonical link. Set it on a page served from more than one URL, like 404.qmd.

A page with none of the first three gets no description tag at all, so give every page a description or a subtitle.

og:url is emitted for every page except 404.html, which is served from any URL depth and so claims none of its own.

Framed embeds

.embed-art frames an embedded document or an image as a tilted card, centred without a wrapper.

![](handout.pdf){.embed-art loading="lazy" title="Typst PDF rendered from the demo source"}

Pandoc writes an image whose target is not an image as a bare <embed> carrying the attributes, so the class applies to <embed> and <img> alike and every declaration lands on the element itself. On an <embed>, title is what gives it an accessible name; loading="lazy" is honoured on an <img> but has no effect there.

The card takes the shape of what it frames, never wider than the column, with the same padding on all four sides. An <img> is framed at its own dimensions, and an <embed> at whatever width and height you give it:

![](handout.pdf){.embed-art width=800 height=600}

An <embed> is the one case with nothing to follow when you give it no size, because a nested browsing context does not report the dimensions of the document inside it. These two properties are what it falls back to, and they have no effect on an image or on an <embed> with a width.

Properties that size an <embed> with no width of its own.
Property Default Effect
--atelier-embed-art-width 560px Width of an <embed> with no width of its own.
--atelier-embed-art-ratio 1.5 Shape of that fallback, as width over height.

One property applies to every card.

The property that applies to every card.
Property Default Effect
--atelier-embed-art-tilt -1.25deg Resting rotation, relaxed toward straight on hover.

The frame, the offset shadow, and the card background are drawn from the page ink and paper, so they follow the colour scheme. Under prefers-reduced-motion: reduce, the card holds its resting angle and does not react to hover at all.

Back to top