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`	`arrow-light` and `arrow-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.

Code blocks show on a tinted surface, with a border and an inset. If you set code-block-bg: false under format.atelier-html, the tint is not shown and code blocks show as outlines. A block with a filename keeps the surface of its code window. The border and the inset stay, so the code stays separate from the text around it. The tint always comes from the brand colours, so a colour value for code-block-bg has no effect. The same is true for typography.monospace.background-color and typography.monospace-block.background-color in _brand.yml, which set code-block-bg. The code surface comes from the brand colours, so the contrast of the syntax highlighting colours on it depends on your brand.

The muted text that Quarto styles on the page, such as the previous and next page links, comes from the page colours and has a contrast of at least 4.5:1 against the page. To change it, set $atelier-text-muted in a project stylesheet under format.atelier-html.theme.

Embedded extensions

Atelier contains five extensions, so you do not install them yourself. The atelier-html format runs their filters and shortcodes on each HTML page. The shortcodes work on HTML pages only: on a page in another format, such as Typst, Quarto stops with “Shortcode ‘iconify’ not found”. Atelier needs the highest Quarto version that its embedded extensions need, so its own minimum version follows theirs.

Extensions that Atelier contains.
Extension	What it does	Options under
iconify	Adds the `{{< iconify >}}` shortcode, for icons from the Iconify sets.	`extensions.iconify`
gitlink	Shows a repository widget in place of a navbar item or sidebar tool with the href `#gitlink-widget`.	`extensions.gitlink`
code-window	Shows a code block that has a `filename` in a window frame with a title bar.	`extensions.code-window`
toc-depth	Sets the table of contents depth below a heading, with the `toc-depth` attribute.	`extensions.toc-depth`
collapse-output	Puts cell output in a collapsible block, with the `output-fold` cell option.	`extensions.collapse-output`

Each extension keeps its own defaults, and its repository lists its options. Atelier changes two defaults. gitlink shows only its widget, and does not change the references in your text. Code Window shows a window only for a block that has a filename, and does not make a label from the language of the other blocks. To turn reference rewriting on, or to give every block a window, set:

extensions:
  gitlink:
    enabled: true
  code-window:
    auto-filename: true

Upgrade from separate copies

If your project has its own copy of one of these five extensions, remove it from _extensions/ and remove its name from your filters list. Quarto looks up the names in your filters list in your own _extensions/ only, so it then runs your copy and the embedded copy, and your copy’s shortcodes replace the embedded ones. Keep your options under extensions:: the embedded copies read them.

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.

Landing page

Atelier has opt-in classes for a landing page: a hero, feature rows and a card grid. Write each block as a fenced div, on a page with page-layout: full and title-block-style: none. The Landing page guide shows each block and its Markdown, and the home page of this site uses them.

::: {.atelier-landing}

::: {.atelier-hero .gradient}

::: {.atelier-hero-text}

# Project name

[One sentence that says what the project does.]{.atelier-lead}

:::

:::

:::

Classes and modifiers of the landing page blocks.
Block	Classes	Modifiers
Container	`.atelier-landing`	None.
Hero	`.atelier-hero`, with the parts `.atelier-hero-text`, `.atelier-hero-figure`, `.atelier-eyebrow`, `.atelier-lead` and `.atelier-actions`	`.split`, `.centred`, `.banner`, `.gradient` and `.glow`
Feature row	`.atelier-feature`, with the parts `.atelier-feature-text` and `.atelier-feature-figure`	`.reverse`
Legend	`.atelier-legend` around an ordered list, with `.atelier-detail` spans	None.
Cards	`.atelier-cards`, which holds `.atelier-card` divs	`.compact`

Modifiers of the landing page blocks.
Modifier	Effect
`.split`	Puts the text part and the figure part side by side. A hero has this layout when it has no other layout modifier.
`.centred`	Centres the text part, in one column. A centred hero has no figure part.
`.banner`	Puts the hero on a tinted surface with a border.
`.gradient`	Fills the hero title (the h1 or the h2) with a gradient that starts at the primary colour.
`.glow`	Puts a soft glow of the primary colour behind the figure.
`.reverse`	Puts the figure part of a feature row on the left.
`.compact`	Makes smaller cards, with the icon and the heading on one line.

The container sets the width of the blocks. On a page that has the container, Atelier hides the title block, because the hero shows the h1. The title of the hero is an h1, or an h2 on a page that has its own h1. Each block stacks into one column below the md breakpoint, and a reversed feature row shows its text part first.

Each colour of the gradient has a contrast of 4.5:1 or more against the page, in each colour scheme. If a colour cannot have this contrast, the hero title uses the primary colour only. In print and in forced colours mode, the hero title is plain text and the glow is removed. Nothing in the blocks moves, so the reduced motion setting has no effect on them.

A card holds an icon, a heading, one sentence and one link. The link covers the whole card, and the focus ring of the link goes around the card. Put only one link in a card, and write link text that says where the link goes. A compact card has no sentence: put its link in the heading.

These Sass variables set the geometry. Set them in the defaults layer of a project stylesheet.

Sass variables of the landing page blocks.
Variable	Default	Effect
`$atelier-landing-max-width`	`1140px`	Maximum width of the container.
`$atelier-landing-gap`	`3rem`	Space between the two parts of a hero or a feature row.
`$atelier-hero-title-size`	`clamp(2.2rem, 5vw, 3.4rem)`	Font size of the hero title.
`$atelier-hero-figure-max-width`	`320px`	Maximum width of the image in the hero figure.
`$atelier-hero-gradient-shift`	`40deg`	Hue difference between the first and the last gradient colour.
`$atelier-card-min-width`	`13rem`	Minimum width of a card column.

These Sass variables set the colours. Atelier calculates each default from the brand for each colour scheme. The gradient check above also applies to gradient colours that you set.

Colour variables of the landing page blocks.
Variable	Default	Effect
`$atelier-landing-accent`	`$primary`, moved to 4.5:1 against the page	Eyebrow, legend numbers, card hover.
`$atelier-landing-muted`	`$text-muted`, moved to 4.5:1 against the page	Lead and legend detail text.
`$atelier-landing-surface`	`body-mix(95%)`	Card and banner surface.
`$atelier-landing-border`	`body-mix(85%)`	Card, banner and feature row borders.
`$atelier-card-muted`	`$text-muted`, moved to 4.5:1 against the card surface	Card text.
`$atelier-card-link`	`$link-color`, moved to 4.5:1 against the card surface	Card link.
`$atelier-hero-gradient-start`	`$atelier-landing-accent`	First colour of the title gradient.
`$atelier-hero-gradient-middle`	The mix of the first and last colours, moved to 4.5:1	Middle colour of the title gradient.
`$atelier-hero-gradient-end`	`$primary` with the hue shift, moved to 4.5:1	Last colour of the title gradient.
`$atelier-hero-glow-color`	`$primary` at 25% opacity	Colour of the glow behind the figure.