BaseLayout is the primary layout component for every page. It renders the full
HTML document including the Nav and Footer components, imports the theme’s
base and component stylesheets, and handles dark mode initialisation.
---
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
---
<BaseLayout title="My page">
<h1>Hello</h1>
<p>Page content goes in the default slot.</p>
</BaseLayout>
Props#
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | --- | Page title, used in the HTML `<title>` element. |
description | string | --- | Page meta description for SEO. |
unlisted | boolean | false | Unlisted page: builds at its URL for anyone with the link, but stays out of the indexes — emits `<meta name="robots" content="noindex">` and marks the page `data-pagefind-ignore="all"` so the on-site search skips it. Set as page frontmatter it also drops the page from llms.txt, which is an index like any other. |
name | string | "Site" | Site name displayed in the nav and footer. |
lang | string | "en" | BCP 47 language of the page, for `<html lang>` (default "en"). |
homeHref | string | --- | Where the nav's logo links (default the site base). |
labels | Partial<ThemeLabels> | --- | Translations of the theme's own chrome (skip link, search, footer); any left out stay English. |
links | NavLink[] | [] | Navigation links displayed in the top bar. |
search | boolean | --- | Whether to show the search button and dialog. |
seoMeta | boolean | true | Emit the description and Open Graph meta tags (default true). Set false when a host framework, such as a CMS head component in the `head` slot, owns SEO meta, so the page doesn't carry two sets. |
clientRouter | boolean | true | Enable Astro's `<ClientRouter>` for view transitions between pages. |
heroTitle | string | --- | Hero section heading text. When provided, renders a Hero component. |
heroImage | string | ImageMetadata | RemoteImage | --- | Hero background image: imported ImageMetadata, a `RemoteImage`, an absolute http(s) URL, or a `/src/assets/...` string path. |
heroImageAlt | string | --- | Alt text for the hero image. Omit (or pass "") for a decorative hero. |
socialImage | string | ImageMetadata | RemoteImage | --- | Card image for link previews (Open Graph / Twitter). Falls back to the site-wide `socialImage`; when neither is set the page emits no `og:image`, and so gets no card. Accepts the same forms as `heroImage`. |
socialImageAlt | string | --- | Alt text for the social card image. |
socialType | "website" | "article" | "profile" | --- | `og:type` for this page; use "article" for posts, "profile" for people. |
favicon | ImageMetadata | --- | Favicon. When omitted, no favicon link is emitted. |
logo | ImageMetadata | --- | Logo image (light mode), passed through to Nav. When omitted, the site name renders as a text wordmark. |
logoDark | ImageMetadata | --- | Logo image (dark mode), passed through to Nav. |
logoCompact | ImageMetadata | --- | Compact logo (crest / monogram) swapped into the nav below the mobile breakpoint, passed through to Nav. |
logoCompactDark | ImageMetadata | --- | Compact logo (dark mode), passed through to Nav. |
colorScheme | "auto" | "light" | "dark" | "auto" | Force a specific colour scheme. 'auto' (default) lets users toggle. |
mainAttrs | HTMLAttributes<"main"> | {} | Extra attributes spread onto the theme's `<main>` element (e.g. `data-pagefind-body` to scope search indexing to page content without wrapping the slot in an extra element, which would break `.at-main`'s subgrid placement). A `class` is merged after the theme's own `at-main`; don't pass `id` (the theme sets `id="main"` as the skip-link target). |
contact | ContactInfo | --- | Contact details displayed in the footer. |
socials | SocialLink[] | --- | Social media links displayed as icons in the footer. |
licence | string | --- | SPDX licence identifier for the site content (e.g. "CC-BY-4.0"). |
acknowledgement | AcknowledgementInfo | --- | Institutional acknowledgement with an optional logo for the footer's dark band. The theme ships no institutional defaults — branding packages supply this as data. |
legalLinks | { text: string; href: string }[] | --- | Footer legal links. |
partnerships | { text: string; href: string; logo: string }[] | --- | Footer partnership logo links, shown in the dark band. |
meta | string[] | --- | Footer regulatory metadata lines (e.g. provider IDs, ABN). Each line is rendered via `set:html`, so callers can embed inline `<a>` markup; values must come from a trusted source. |
Hero banner#
Two ways to add a hero banner to a page. In .astro files, use the named hero
slot with the Hero component directly:
---
import bannerImage from "../assets/images/banner.avif";
---
<BaseLayout title="Home">
<Hero slot="hero" title="Welcome" image={bannerImage} />
<p>Page content.</p>
</BaseLayout>
The image prop accepts an imported image (ImageMetadata), processed through
Astro’s image pipeline for optimisation, or a RemoteImage object
({ src, width?, height?, srcset?, sizes? }) for a pre-encoded external source
— a CDN or object-store URL — rendered as a plain <img> with no build-time
processing.
For MDX pages, wrap content in the layout component directly to pass imported images:
import PageLayout from "../layouts/PageLayout.astro";
import heroImage from "../assets/images/campus.avif";
<PageLayout title="About" heroTitle="About us" heroImage={heroImage}>
Page content here as markdown.
</PageLayout>
If both heroTitle and a slot="hero" are provided, both will render — so
pick one approach per page.
What it includes#
BaseLayout renders the complete HTML document. Inside, it provides:
- a skip-to-main-content link for keyboard navigation
- the
Navcomponent with your site name (as a text wordmark, or a logo if you pass one) and links - a
<main>element that receives the default slot content - the
Footercomponent with contact info, social links, acknowledgement, and licence - a favicon link, but only when you pass a
faviconimage — there’s no default - Open Graph and Twitter card meta for link previews (see social cards below)
- an inline script that reads the user’s theme preference from
localStorageand applies it before first paint, preventing a flash of the wrong theme
The layout also imports base.css and components.css from the theme, so you
don’t need to add those yourself.
Social cards#
Every page emits Open Graph and Twitter card meta, so a link pasted into Slack,
Discord or a social feed renders as a card rather than a bare URL. Title,
description and site name come from props you already pass; og:url and a
canonical link are added when your Astro config declares a site.
The one piece with no fallback is the image. Scrapers derive og:title from
<title> and og:description from the meta description, but a page with no
og:image gets no card at all — so set one:
// src/site-config.ts
import card from "./assets/card.png";
export const siteConfig = defineSiteConfig({
name: "Your University",
socialImage: card,
socialImageAlt: "The Your University wordmark on a deep teal field",
});
Any page can override it, and MDX pages can do so from frontmatter:
---
title: Annual report
socialImage: /src/assets/reports/annual-2027-card.png
socialImageAlt: The 2027 annual report cover
---
A local image is encoded to a JPEG card 1200px wide at build time, because
card scrapers largely don’t decode AVIF or WebP — so pointing socialImage at
the same AVIF you use for a hero is fine. A pre-encoded card hosted elsewhere
can be passed as a RemoteImage instead, and is used as-is. Pages with no image
still emit the text tags and declare twitter:card as summary rather than
summary_large_image.
Use socialType for pages that aren’t ordinary pages — "article" for posts
and news, "profile" for people.
Other languages#
lang sets <html lang>, which also decides the language Pagefind indexes a
page under, so each language gets its own search results. labels translates
the theme’s own chrome: the skip link, the nav’s menu and search buttons, the
search dialog and the footer. Pass any of the ThemeLabels keys (exported from
astro-theme-university/labels with their English defaults); the rest stay
English. noResults takes a {query} placeholder and licence a {licence}
one. homeHref points the logo at the current language’s home page.
<BaseLayout
title="Themen"
lang="de"
homeHref="/de/"
labels={{ menu: "Menü", search: "Suche", skipToContent: "Zum Inhalt springen" }}
>
Site config pattern#
Most props on BaseLayout are the same across every page — site name, navigation links, footer details. Rather than repeating them, define a shared config object and spread it. See configuration for the full pattern.