Carousels

The carousel directive turns a list of images or content blocks into a responsive Slick carousel. It accepts Markdown images, list items, raw HTML <div> elements and FrontMark ::: container blocks.

Syntax

Form	Syntax	Usage
Carousel	`::: carousel { ... }`	Component wrapper.
Image slide	`![Alt](/image.jpg)`	One direct image per slide.
List	`- ![Alt](/image.jpg)`	One list item per slide.
Container slide	`::: container { ... }`	Rich FrontMark content.
HTML slide	`<div>...</div>`	Arbitrary static HTML.
Multi-block slide	Separate slides with `---`	Group a heading, text and media.

The default configuration matches the standard FrontMark slideshow:

{
  autoplay: true,
  autoplaySpeed: 4000,
  pauseOnHover: true,
  pauseOnFocus: true,
  dots: true,
  slidesToShow: 1,
  arrows: false,
  lazyLoad: "ondemand",
  focusOnSelect: true
}

Image carousel

Each direct image is a slide. Camel case and kebab case are both accepted for option names.

SyntaxResult

::: carousel { autoplay=true autoplaySpeed=4000 pauseOnHover=true pauseOnFocus=true dots=true slidesToShow=1 arrows=false lazyLoad=ondemand focusOnSelect=true aria-label="FrontMark gallery" aspect-ratio="16/7" image-fit=cover }

![FrontMark visual](https://dummyimage.com/1200x525/062b42/e8f7fa&text=FrontMark)

![Markdown visual](https://dummyimage.com/1200x525/0d6f84/f8fafc&text=Markdown)

![Astro visual](https://dummyimage.com/1200x525/114c64/f8fafc&text=Astro)

:::

Markdown list

When the directive contains one Markdown list, every list item becomes a slide. An item may contain an image plus a caption or other Markdown.

SyntaxResult

::: carousel { autoplay=false arrows=true dots=true lazyLoad=progressive aria-label="Photo list" }

- ![First landscape](https://dummyimage.com/1200x525/001522/f8fafc&text=Landscape+1)
- ![Second landscape](https://dummyimage.com/1200x525/073047/f8fafc&text=Landscape+2)
- ![Third landscape](https://dummyimage.com/1200x525/246078/f8fafc&text=Landscape+3)

:::

FrontMark containers

Direct ::: container children are preserved as complete slides. This is useful for calls to action, feature cards and mixed Markdown content.

SyntaxResult

::: carousel { autoplay=false adaptiveHeight=true arrows=true dots=true aria-label="Feature cards" }

::: container { predef=rounded-callout align=center pad=2rem }
## Portable Markdown

Keep the source readable and let FrontMark handle presentation.
:::

::: container { predef=soft-bordered align=center pad=2rem }
## Rich components

Add images, links, icons and other supported Markdown blocks.
:::

::: container { predef=cta-halo align=center pad=2rem }
## Responsive by default

Swipe on touch screens or use the optional arrows and dots.
:::

:::

Portable Markdown

Keep the source readable and let FrontMark handle presentation.

Rich components

Add images, links, icons and other supported Markdown blocks.

Responsive by default

Swipe on touch screens or use the optional arrows and dots.

HTML slides

A complete raw HTML <div> is treated as one slide. Keep a blank line between sibling elements and before the closing ::: marker.

SyntaxResult

::: carousel { autoplay=false arrows=true dots=true adaptiveHeight=true aria-label="HTML cards" }

<div style="min-height: 13rem; padding: 2rem; border-radius: .75rem; background: #073047; color: #f8fafc;">
  <h3>HTML slide</h3>
  <p>Any static HTML can live inside a carousel slide.</p>
</div>

<div style="min-height: 13rem; padding: 2rem; border-radius: .75rem; background: #114c64; color: #f8fafc;">
  <h3>Second slide</h3>
  <p>Use semantic HTML and keep interactive controls keyboard accessible.</p>
</div>

:::

HTML slide

Any static HTML can live inside a carousel slide.

Second slide

Use semantic HTML and keep interactive controls keyboard accessible.

Multi-block slides

By default, each top-level Markdown block is a slide. Add a thematic separator (---) when one slide must contain several blocks.

SyntaxResult

::: carousel { autoplay=false arrows=true adaptiveHeight=true }

## First topic

A paragraph and its heading stay together because the next slide starts at `---`.

---

## Second topic

This heading and paragraph form the second slide.

:::

First topic

A paragraph and its heading stay together because the next slide starts at ---.

Second topic

This heading and paragraph form the second slide.

Multiple slides and responsive breakpoints

Use a JSON array in responsive for breakpoint-specific settings. Slick uses desktop-first breakpoints unless mobileFirst=true.

SyntaxResult

::: carousel { autoplay=false arrows=true dots=true slidesToShow=3 slidesToScroll=1 gap=1rem responsive='[{"breakpoint": 900, "settings": {"slidesToShow": 2}}, {"breakpoint": 620, "settings": {"slidesToShow": 1, "arrows": false}}]' }

<div style="padding: 3rem 1rem; text-align: center; background: #062b42; color: white;">One</div>

<div style="padding: 3rem 1rem; text-align: center; background: #0d6f84; color: white;">Two</div>

<div style="padding: 3rem 1rem; text-align: center; background: #114c64; color: white;">Three</div>

<div style="padding: 3rem 1rem; text-align: center; background: #246078; color: white;">Four</div>

:::

One

Two

Three

Four

Options

Option names may use Slick camel case (slidesToShow) or Markdown-friendly kebab case (slides-to-show). Values are validated before being included in the generated page.

Option	Type	FrontMark default	Purpose
`autoplay`	Boolean	`true`	Advance slides automatically.
`autoplaySpeed`	Milliseconds	`4000`	Delay between automatic changes.
`pauseOnHover`	Boolean	`true`	Pause while the pointer is over the carousel.
`pauseOnFocus`	Boolean	`true`	Pause while a child has keyboard focus.
`dots`	Boolean	`true`	Show paging indicators.
`arrows`	Boolean	`false`	Show previous and next buttons.
`slidesToShow`	Integer	`1`	Number of visible slides.
`slidesToScroll`	Integer	`1`	Number of slides moved at once.
`focusOnSelect`	Boolean	`true`	Move to a selected slide.
`lazyLoad`	`ondemand`, `progressive`, `anticipated`, `false`	`ondemand`	Defer image loading.
`adaptiveHeight`	Boolean	`false`	Follow the current slide height.
`infinite`	Boolean	`true`	Loop back to the first slide.
`fade`	Boolean	`false`	Cross-fade instead of sliding; use with one visible slide.
`speed`	Milliseconds	`500`	Transition duration.
`centerMode`	Boolean	`false`	Center the current slide with adjacent previews.
`centerPadding`	CSS length	`50px`	Side padding used by center mode.
`initialSlide`	Integer	`0`	Zero-based initial slide.
`draggable`, `swipe`, `touchMove`	Boolean	`true`	Pointer and touch interaction.
`swipeToSlide`	Boolean	`false`	Swipe directly to a slide regardless of `slidesToScroll`.
`vertical`, `verticalSwiping`	Boolean	`false`	Vertical layout and gestures.
`variableWidth`	Boolean	`false`	Preserve individual slide widths.
`rows`, `slidesPerRow`	Integer	`1`	Grid mode.
`rtl`	Boolean	`false`	Right-to-left movement.
`mobileFirst`	Boolean	`false`	Interpret responsive breakpoints from small to large.
`responsive`	JSON array	none	Breakpoint-specific settings or `"unslick"`.
`accessibility`	Boolean	`true`	Keyboard navigation and ARIA state.

Component-only presentation attributes are also available:

Attribute	Example	Purpose
`aria-label`	`aria-label="Project gallery"`	Accessible carousel name.
`height`	`height=28rem`	Fixed slide and image height.
`aspect-ratio`	`aspect-ratio="16/9"`	Responsive image ratio.
`image-fit`	`cover`, `contain`	Image object fitting.
`gap`	`gap=1rem`	Space between visible slides.
`#id` / `.class`	`#gallery .wide`	Custom hook on the component wrapper.

Theme-aware styling

Carousel controls automatically inherit the active FrontMark theme. Their surface uses the theme panel color, while borders and dots use its accent color and arrow icons use its text color. This also follows live light/dark changes in switchable themes.

Add a custom class to override only the controls for one carousel:

::: carousel .brand-gallery { arrows=true dots=true }
...
:::

.brand-gallery {
  --mkdocs-carousel-control-background: rgb(255 255 255 / 92%);
  --mkdocs-carousel-control-hover-background: #f1f5f9;
  --mkdocs-carousel-control-border: #0f766e;
  --mkdocs-carousel-control-color: #134e4a;
  --mkdocs-carousel-control-shadow: 0 0.45rem 1.4rem rgb(15 23 42 / 20%);
}

The arrow buttons remain vertically centered on the slide viewport whether dots are enabled or not. An isolated foreground layer also keeps them above positioned HTML and FrontMark containers inside a slide. Focus outlines, reduced-motion preferences and forced-color mode are handled automatically.