Skip to main content

BaseLayout

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:

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.