# BaseLayout

> The main page wrapper that provides navigation, footer, and theme support.

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.

```astro
---
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

<PropsTable component="layouts/BaseLayout" />

## 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:

```astro
---
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:

```mdx
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 `Nav` component 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 `Footer` component with contact info, social links, acknowledgement, and
  licence
- a favicon link, but only when you pass a `favicon` image --- there's no
  default
- Open Graph and Twitter card meta for link previews (see
  [social cards](#social-cards) below)
- an inline script that reads the user's theme preference from `localStorage`
  and 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:

```js
// 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:

```yaml
---
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.

```astro
<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](https://anucybernetics.github.io/astro-theme-university/docs/getting-started/configuration/#site-config) for the full
pattern.
