Containers are full-width Markdown sections with a background, optional image layer, top and bottom raccord masks, motion, borders, filters and responsive visibility.

Inline example:

::: container { bg="linear-gradient(135deg, #0f766e, #1d4ed8)" align=center valign=middle mask-top=dunes-gray mask-bottom=wave-gray }
## One masked section

Any Markdown can live here.
:::

::: container { bg="linear-gradient(135deg, #0f766e, #1d4ed8)" align=center valign=middle mask-top=dunes-gray mask-bottom=wave-gray } ceci est un test :::

Use onclick or onhover to make the container surface navigate to a URL or run JavaScript. Root-relative internal URLs automatically receive site.base. HTTP(S), protocol-relative, root-relative, ./, ../, hash, mailto: and tel: values are recognized as URLs. Prefix another URL form with url: when needed.

::: container { onclick="/docs/getting-started/" aria-label="Open the getting started guide" }
## Open the guide

Click anywhere on this surface.
:::

::: container { onclick="https://example.com" target=_blank }
Open an external site in a new tab.
:::

Prefix JavaScript with js:. An onclick value that is not recognized as a URL is also treated as JavaScript, so the prefix is optional but recommended for clarity. The handler receives the browser event, and this is the container element.

::: container { onclick="js:this.classList.toggle('is-selected')" onhover="js:this.dataset.hovered='true'" }
This container reacts to click and pointer hover.
:::

onclick containers are focusable and activate with Enter or Space. Clicking a nested link, button, input, select, text area, or summary keeps that control’s own behavior and does not also activate the container. onhover maps to mouseenter, so it is pointer-only; do not put an essential action exclusively on hover. Add aria-label when the visible text does not clearly describe a click action.

JavaScript actions execute as trusted page code. Only use them in Markdown that is controlled by trusted authors; prefer URL actions whenever navigation is sufficient.

Add grid=position/total to consecutive containers to create an explicit row. total can be any integer greater than one: the feature is not limited to three columns. Positions must stay between 1 and total and increase in the row, for example 1/4, 2/4, 3/4, 4/4. A repeated position, a different denominator, or any normal block starts a new group.

On screens narrower than 40rem, an explicit row becomes one column so its content remains readable. grid-gap (or gap) controls the space between items; set it on the first container in the row.

::: container { grid=1/4 grid-gap=1rem }
First card
:::

::: container { grid=2/4 }
Second card
:::

::: container { grid=3/4 }
Third card
:::

::: container { grid=4/4 }
Fourth card
:::

The following illustration is the live rendered result, not a static image:

You can also leave slots empty. For example, grid=2/5 followed by grid=4/5 uses the second and fourth columns of a five-column row.

Use grid=flex when the number of items per row should depend on available space. grid-size is the preferred width of an item; plain numbers are treated as pixels and CSS lengths such as 15rem, 280px, or 30% are accepted. The first item defines the group default. A later item may set its own grid-size to override that width.

::: container { grid=flex grid-size=15rem grid-gap=1rem }
First flexible card
:::

::: container { grid=flex }
Second flexible card
:::

::: container { grid=flex }
Third flexible card
:::

Resize the page to see this live illustration wrap automatically:

Only consecutive containers with the same grid mode are grouped. Insert a heading, paragraph, divider, or a container without grid to end the row.

Use root=top for an Astro hero that spans the viewport and starts at its top, behind the navigation. root=true is an alias for the same behavior. The navigation becomes an overlay and normally scrolls away with the first viewport. Set the page frontmatter option scrollonpage: true to turn a downward wheel, touch, or keyboard gesture made inside the first root=top section into a smooth jump to its end. The behavior remains armed while the visitor is anywhere inside that section and adapts to its rendered height. Without a top-root section, the current viewport height is used. Scrolling is native from the section boundary onward, and the behavior becomes available again whenever the visitor returns inside the first section. Set header.alwaysOnTop: true in page frontmatter when it must remain fixed. Use header.alwaysOnTop: transparent to keep it fixed and transparent at the top, then restore the active style surface after header.transparentScrollY pixels (100 by default). Use root-header=light (the default), dark, or current to match the hero image. This option only controls the navigation contrast while a root=top container is present; it does not control when the container is displayed. Responsive container visibility remains configured with visible, hidden, hide-mobile, and the other visibility attributes.

The navigation surface is transparent by default on a top-root section. Set root-header-transparent=false to keep the active theme background instead. root-menu-transparent is accepted as an alias.

The root container must be the first visible block of a full-layout Astro page. This avoids a generated title or back button being covered by the hero.

See Page shell, header and first-screen scrolling for the configuration precedence, input behavior, responsive rules and troubleshooting.

Open the full-size Root Container example on Getting Started

---
title: "Preserve a heritage"
layout: full
scrollonpage: true
---

::: container { root=top root-header=light root-header-transparent=true root-content-width=76rem height=100svh image="/images/heritage.jpg" fg="#fff" align=left valign=bottom pad="clamp(2rem, 6vw, 5rem)" }
01

# Preserve a heritage

Scientific documentation for exceptional underground sites.
:::

The documentation keeps this preview inside a frame. On a full-layout Astro page, the same inner root container expands to the complete viewport.

Use root=flow when the section should span the complete viewport width but remain at its normal position in the page. In documentation mode a root container also stays in the document flow, so it cannot cover the Starlight sidebar or the generated page title.

root-content-width controls the maximum width of the inner Markdown while the background remains edge to edge.

Use predef=type to choose a complete preset. Use predef=type_color to force a gradient color such as ink-accent, deep-bright, panel-soft, ink-header, ink-teal, or night-warning.

::: container { bg="#2563eb" align=center valign=middle height=260 }
## Solid background

The section uses one flat color.
:::

::: container { bg="linear-gradient(135deg, #0ea5e9 0%, #6366f1 58%, #7c3aed 100%)" align=center valign=middle height=300 }
## Gradient background

Any valid CSS background value can be used.
:::

::: container { bg="#4f46e5" align=right valign=middle height=280 mask-top=triangle mask-bottom=curve mask-bottom-invert=y }
## Triangle and curve
:::

::: container { bg="#2563eb" image="/images/parallax/mountains-back.svg" mask="/images/container/mask-radial.svg" align=left valign=middle height=420 mask-bottom=diagonal-wave }
## Masked image

- `image` defines the background layer.
- `mask` applies the image mask.
:::

Add responsive=profile beside image to use the same Asset Manager profiles as normal Markdown images. The container requests the smartphone preset up to 767px, the tablet preset up to 1199px, and the desktop preset above that.

::: container { bg="#0f172a" image="https://assets.ia86.cc/i/e9Q4a_pnYN.webp" responsive=hero fg="#fff" align=center valign=middle height=420 }
## Responsive container background

The background URL and Asset Manager preset follow the viewport width.
:::

The available profiles are icone, avatar, miniature, carte, contenu, article, banniere, hero, and herohd. A custom three-preset value such as responsive="small,card,hero" is also accepted in smartphone, tablet, desktop order. As with responsive Markdown images, src-mobile, src-tablet, and src-desktop can select different source files before the preset is appended; src-smartphone is an alias for src-mobile. Missing sources fall back from mobile to tablet to desktop, with image as the final desktop source. Every named profile uses three distinct, increasing presets; notably, icone maps to micro, icon, miniature, while avatar maps to icon, miniature, thumbnail. Asset Manager still caps the effective result at the source image resolution, so use a sufficiently large original for the desktop preset.

::: container { predef=lateral-double-waves config=true }
## Lateral raccords

The lateral style is handled by the predefined surface.
:::

::: container { predef=side-capsule-right config=true }
## Large lateral round

The wide rounded side is handled by the capsule preset.
:::

::: container { bg="linear-gradient(135deg, #1d4ed8 0%, #0f172a 100%)" align=center valign=middle height=280 border-width=4px border-color="rgba(191, 219, 254, 0.82)" radius=2rem }
## Colored border

The transparent outside area remains visible around the rounded edge.
:::

::: container { bg="#334155" align=center valign=middle height=260 filter-sepia=1 filter-opacity=50% }
## Sepia and 50% opacity

Filters affect the inner Markdown content.
:::

::: container { bg="#0ea5e9" align=center valign=middle height=180 visible=mobile }
## Smartphone only
:::

::: container { bg="#14b8a6" align=center valign=middle height=180 visible=tablet }
## Tablet only
:::

::: container { bg="#6366f1" align=center valign=middle height=180 visible=desktop }
## Desktop only
:::

::: container { bg="linear-gradient(135deg, #0f766e, #111827)" align=center valign=middle height=300 mask-bottom=gray-wavelets anim=slide-up duration=2s }
## Animated section

Free Markdown content.
:::

::: container { bg="linear-gradient(135deg, #06b6d4 0%, #3b82f6 48%, #8b5cf6 100%)" align=stretch valign=middle height=360 mask-top=dunes-gray mask-bottom=clouds-gray shadow=light }
### Complete section

| Element | Role |
| --- | --- |
| Background | Color, gradient, image and mask |
| Shadow | Optional depth behind the section |
| Transition | Top and bottom masks |

:::

Raccords are now rendered as one CSS mask on the container surface. Use mask-top=<shape> and mask-bottom=<shape>. The top and bottom can be different, and the bottom is mirrored automatically.

::: container { bg="linear-gradient(135deg, #0f766e, #1d4ed8)" mask-top=dunes-gray mask-bottom=wave-gray }
## Dunes and wave
:::

::: container { bg="#4f46e5" mask-top=triangle mask-bottom=curve mask-bottom-invert=y }
## Triangle and curve
:::

Use anim=<name>, duration=<time> and delay=<time>. Hover the chips to preview the motion.

Set a site-wide default delay in milliseconds with site.animationdelay:

site:
  animationdelay: 180

The delay starts when an animated element enters the viewport. It applies to every anim= block that does not declare its own delay= value. A local value such as delay=400ms overrides the site default for that block. Use 0 to disable the global delay. site.animationDelay is accepted as a camel-case alias, and PUBLIC_ANIMATION_DELAY can override the value at build time.