Page shell, header and first-screen scrolling

FrontMark can keep the header in the document flow, fix it with its normal theme surface, or make it transparent only near the top of the page. A page can also turn the first downward gesture into a smooth move to the end of its opening section.

These options work on both Astro Markdown pages in src/content/astro/ and Starlight documentation pages in src/content/docs/.

Configuration levels

The same page can receive settings from three places. The most specific value wins.

Level	Configuration	Scope
Active style	`theme.availableStyles[].header` in `site.config.yaml`	Default for every page using that style.
Astro style	`theme.availableStyles[].astro.showBackToTop`	Show or hide the return-to-top control for Astro pages using that style.
Page	`header` and `scrollonpage` in Markdown frontmatter	Override for the current page.
Opening container	`root`, `root-header`, `root-header-transparent`	Position and contrast of one top-root section.

Page frontmatter overrides the active style for header.alwaysOnTop and header.transparentScrollY. If a page omits them, changing style also changes the header behavior to the selected style configuration.

Header position modes

header.alwaysOnTop accepts five values.

Value	Position	Surface while scrolling
`false`	The header follows the document and leaves the viewport.	The active theme surface is unchanged.
`true`	The header remains fixed.	The active theme surface is always visible.
`transparent`	The header remains fixed.	Transparent before the threshold, then restored to the active theme surface.
`transparent_white_in_mini`	The header remains fixed.	Same progressive transparency, with a white responsive menu button and black icon.
`transparent_black_in_mini`	The header remains fixed.	Same progressive transparency, with a black responsive menu button and white icon.

The transparent state removes the theme background, border, shadow, backdrop blur and decorative header layers. Once the page reaches transparentScrollY, the normal theme colors and decorations return. The two _in_mini modes preserve the existing responsive icon exactly as it is—book or classic sandwich depending on the current shell—and only override its background and foreground colors on tablet and smartphone layouts.

Configure a style-wide default in site.config.yaml:

site.config.yaml

theme:
  availableStyles:
    - name: underground
      stylesheet: /styles/themes/underground/theme.css
      header:
        alwaysOnTop: transparent
        transparentScrollY: 100

transparentScrollY is a non-negative pixel value and defaults to 100. PUBLIC_HEADER_TRANSPARENT_SCROLL_Y can replace the active style threshold at build time.

Optionally set brand.logo2 to use a dedicated logo over the transparent header. It is displayed below transparentScrollY; at the threshold the header switches back to brand.logo. Without logo2, the primary logo remains visible in both states.

site.config.yaml

brand:
  logo: /brand/logo.png
  logo2: /brand/logo-transparent.png

Override one page

Use the same nested keys in frontmatter:

Page frontmatter

---
title: "Getting Started"
layout: full
header:
  indexMenu: normal
  alwaysOnTop: transparent
  transparentScrollY: 100
---

The page override remains active when the visitor changes style. Remove the override when each style should retain its own header behavior.

Full-height opening section

Use a first root=top container on a full-layout Astro page to place the hero at the exact top of the viewport, behind the header.

::: container { root=top height=100svh root-header=light root-header-transparent=true bg="#111827" fg="#fff" valign=middle }
# Opening screen

This section fills the current screen.
:::

Attribute	Purpose
`root=top`	Escapes the content column and anchors the first section at the viewport top. `root=true` is an alias.
`height=100svh`	Uses the current small viewport height, including responsive mobile layouts.
`root-header=light`	Uses light header text over a dark hero. Use `dark` over a light hero or `current` to keep the theme tone.
`root-header-transparent=true`	Makes the navigation surface transparent over the opening container.

root-header-transparent controls the container overlay. It does not by itself define a scroll threshold. Combine it with header.alwaysOnTop: transparent when the fixed header must regain its nominal surface after a number of pixels.

The top-root offset includes the active header height and any theme decoration overhang. Themes such as Caving and Mountains therefore align the hero at 0px without a page-specific negative margin. Keep the root container as the first visible block; generated titles or content placed before it prevent a true opening-screen layout. In documentation mode, root containers deliberately stay in the content flow so they cannot cover the Starlight navigation.

First-screen scrolling

Enable the behavior on one page with scrollonpage: true. The camel-case alias scrollOnPage is accepted, but the lowercase spelling is preferred.

Page frontmatter

---
layout: full
scrollonpage: true
header:
  alwaysOnTop: transparent
  transparentScrollY: 100
---

While the current scroll position is inside the first root=top section, one downward gesture moves smoothly to that section’s exact rendered end.

Input	Trigger
Mouse or trackpad	Wheel movement with a positive vertical delta.
Touch	Upward finger movement, which requests downward page scrolling.
Keyboard	`ArrowDown`, `PageDown`, or `Space`.

The boundary is recalculated for the current screen and content height on every gesture. If no root=top section exists, FrontMark uses the current viewport height as a fallback. Native scrolling resumes at the section boundary, and the feature becomes available again whenever the visitor returns inside the first section; it is not limited to the first gesture after page load.

Upward gestures remain native. FrontMark also leaves editable fields alone and lets independently scrollable nested elements consume the gesture until they reach their lower boundary. With prefers-reduced-motion: reduce, the destination is unchanged but the movement is immediate instead of animated.

Set scrollonpage: false or omit the field to keep native scrolling everywhere.

Astro return-to-top button

Astro pages can display the same translated return-to-top action used by the documentation shell. Configure a default under astro, then override it for individual themes:

site.config.yaml

astro:
  showBackToTop: false

theme:
  availableStyles:
    - name: underground
      astro:
        showBackToTop: true

The control appears only after the page has scrolled down, contains the shared up-arrow icon, and uses the backToTop interface translation for the active site language. Changing themes in the development selector updates its visibility immediately. This setting is independent from showBackButton, which controls the small return-to-home icon near the beginning of a normal Astro page.

Complete recipe

This is the combination used by the Astro Getting Started demonstration:

src/content/astro/getting-started.md

---
title: "Getting Started"
description: "Clone FrontMark and launch the local preview."
layout: full
scrollonpage: true
header:
  indexMenu: normal
  alwaysOnTop: transparent
  transparentScrollY: 100
---

::: container { root=top height=100svh root-header=light root-header-transparent=true bg="linear-gradient(135deg, #080b0d, #5d3218)" fg="#fff" align=center valign=middle }
# Getting Started

The navigation starts transparent and becomes nominal after 100 pixels.
:::

## The next section

Normal page scrolling continues here.

Open the live Getting Started page

Troubleshooting

Symptom	Check
The header leaves the viewport.	`header.alwaysOnTop` resolves to `false` in the page or active style.
The header never regains its theme surface.	Use `alwaysOnTop: transparent`; `root-header-transparent=true` alone does not configure a threshold.
A blur or decorative shape is visible at the top.	Check local CSS overrides: the built-in transparent state disables both.
Space appears above the hero.	Keep `root=top` as the first visible block of a `layout: full` Astro page and avoid overriding its root margin.
The jump stops at an unexpected point.	Check the rendered height of the first `root=top` container; the destination is its bottom edge, not a hard-coded pixel value.

See Markdown Containers for every root container attribute and Going further for the complete theme configuration.