Skip to main content

Configuration

Theme options

The universityTheme() integration accepts an optional configuration object.

// astro.config.ts
import { defineConfig } from "astro/config";
import universityTheme from "astro-theme-university";

export default defineConfig({
  integrations: [
    universityTheme({
      name: "My Research Group",
      checkLinks: true,
      checkA11y: true,
      checkTokens: true,
    }),
  ],
});
Prop Type Default Description
name string --- Site name displayed in the header and meta tags
defaultLayout string --- Default layout for MDX pages without an explicit layout in frontmatter. Path relative to the project root, e.g. "src/layouts/PageLayout.astro".
search boolean --- Build a Pagefind search index after build (default: true)
checkLinks boolean --- Check for broken internal links after build (default: true)
checkA11y boolean --- Check for accessibility violations after build (default: true)
checkTokens boolean --- Fail the build on `var(--at-*)` references to tokens nothing defines (default: true)
llmsTxt boolean | { extra?: () => string | undefined | Promise<string | undefined> } --- Generate /llms.txt, /llms-full.txt and a markdown twin of every indexed page from content collections and src/pages markdown (default: false). The object form's `extra` returns markdown placed between the preamble and the page index, for context the site generates from its own data.
citation string | false --- CITATION.cff the site is cited from, relative to the project root (default: "CITATION.cff"; false turns citation off). When the file exists, every page's head carries schema.org JSON-LD and a `cite-as` link, and the llms outputs carry a "Citing this site" block and a source/licence/cite-as footer on each page. `preferred-citation` fields win over the top-level ones.
mdx boolean --- Auto-register the
icon boolean --- Auto-register the astro-icon integration so consumers can use <Icon> from astro-theme-university/components/Icon.astro (default: true)
fonts boolean --- Auto-register the theme fonts (Public Sans + Roboto Mono) via Google (default: true)
preloadFonts string[] --- cssVariables of registered fonts that BaseLayout should preload — list fonts that are visible above the fold on most pages. Applies to the theme fonts and any fonts the site registers via the top-level `fonts` config. (default: ["--font-public-sans"], the theme body font)
imageFormat ImageOutputFormat --- Output format for the images the theme's own components render (Card, Hero). AVIF is roughly half the bytes of WebP for the same quality but around 8x slower to encode, so it only pays off where the build caches image transforms between runs. Individual call sites can still override this with an `imageFormat` prop. An SVG source ignores all of that and is passed through unrasterised, since Astro can only rasterise one with `image.dangerouslyProcessSVG` set. (default: "webp")
brandCss string | string[] --- Module specifier(s) of brand CSS to import globally on every page, e.g. "my-university-brand/brand.css". The theme's own palette declarations are layered (`@layer at.tokens`), so unlayered brand declarations win the cascade regardless of load order.
decks boolean | DeckOptions --- Register astromotion for `.deck.mdx` slide decks under `src/decks/`, with the theme's deck stylesheet and body font as defaults and the deck remark plugins appended to the theme's markdown chain. Pass an object to forward astromotion options (`routePrefix`, a custom `theme`, …). Ignored, with a warning, when the site registers astromotion itself — then it also owns the remark plugins (`extraRemarkPlugins: deckRemarkPlugins`). (default: false)
extraRemarkPluginsBefore RemarkPlugins --- Extra remark plugins to run BEFORE the theme's default list — e.g. a topic splicer whose output must then flow through the theme's directive plugins (custom heading ids, callouts).
extraRemarkPlugins RemarkPlugins --- Extra remark plugins to append to the theme's default list.
extraRehypePlugins RehypePlugins --- Extra rehype plugins to append to the theme's default list.

checkLinks, checkA11y and checkTokens all default to true; set any to false to skip it temporarily. When the site is deployed under a base sub-path, checkLinks also verifies that every rendered internal link carries the base prefix (see base-path-aware links).

checkTokens fails the build on a var(--at-*) reference to a custom property nothing defines. --at- is the theme’s namespace, so a name it doesn’t define is a typo or an invention, and a fallback makes it worse: the literal quietly becomes the real value and stops following the colour scheme, which reads as correct in one mode and unreadable in the other. Give your own variables your own prefix.

Default layout

The defaultLayout option injects a layout into MDX pages under src/pages/ that don’t specify one in frontmatter. This means individual pages don’t need a layout: field or a wrapping layout component — just frontmatter and content:

// astro.config.ts
universityTheme({ defaultLayout: "src/layouts/PageLayout.astro" });
---
title: My page
heroTitle: Welcome
heroImage: /src/assets/images/hero.avif
---

Content here --- no layout import needed.

Frontmatter hero images

When using defaultLayout, MDX pages can specify hero images as paths in frontmatter instead of importing them. Pass a path starting with /src/assets/ and BaseLayout resolves it to ImageMetadata via import.meta.glob, so the image goes through Astro’s optimisation pipeline automatically:

---
heroImage: /src/assets/images/hero/campus.avif
heroTitle: About us
---

The path must point to an image file within the src/assets/ directory tree.

An absolute http(s):// URL also works, for images hosted outside the site (a CDN or object-store bucket). A remote hero bypasses Astro’s image pipeline and renders as a plain <img> — the hero’s CSS handles layout, so no dimensions are needed:

---
heroImage: https://img.example.com/heroes/campus.avif
heroTitle: About us
---

For remote images with responsive variants, pass a RemoteImage object ({ src, width?, height?, srcset?, sizes? }) to the layout’s heroImage prop from a page’s own frontmatter-free code instead.

LLM content

When llmsTxt: true is set, the theme generates /llms.txt and /llms-full.txt at build time. The page index is auto-generated from your content collections and any markdown or MDX files under src/pages/, but the preamble at the top of llms.txt is hand-written.

Create src/llms.md with a title, description, and any context you want LLMs to have about your site:

# My Research Group

> Interdisciplinary research at Example University.

This site documents our projects, publications, and team members. Key areas
include quantum computing, climate modelling, and policy analysis.

The theme appends a line linking /llms-full.txt with its size, then the page index: every published page with its title and description, grouped into one ## section per top-level path that holds more than one page (headed by that path’s listing page title), with the rest under ## Pages. Numbered URLs sort numerically, so week-10 follows week-9. If src/llms.md doesn’t exist, the theme falls back to a minimal header using the site name from your theme options. Root-relative links in the preamble ([API](/api/index.json)) are rewritten to absolute URLs under your site and base, since an agent reading the file has no page to resolve them against.

Every indexed page also gets a markdown twin beside its HTML, at the HTML path plus .md (/topics/x/ → /topics/x/index.html.md), and its head carries a <link rel="alternate" type="text/markdown"> pointing at that twin — so an agent handed one page’s URL gets that page as markdown rather than the whole-site index. Pages that aren’t indexed (unlisted ones, .astro-only routes) keep a link to /llms.txt instead. The links are emitted only when llmsTxt is on, and respect your configured base path.

For context the site can generate from its own data — key dates, say, which a hand-written preamble would restate and let drift — pass the object form:

universityTheme({
  llmsTxt: { extra: async () => "## Key dates\n\n- Assignment 1: 17 August" },
});

The returned markdown sits between the preamble and the page index.

Entry URLs are derived from each markdown file’s path under src/content/ and src/pages/: the pages collection renders at the site root (src/content/pages/about.md → /about/, matching the definePageCollection catch-all convention), while any other collection keeps its directory name (src/content/news/launch.md → /news/launch/). The build verifies that every entry has a matching page in the output (<url>/index.html or <url>.html) and fails if any entry would point at a page that doesn’t exist — for example when a collection renders under a different route than its directory name implies.

Slide decks are included too, on a site with decks in the build: each deck under src/decks/ is listed at the URL its route serves, and its readable text becomes its markdown twin. Decks are left out of /llms-full.txt, since their prose restates pages it already carries. Speaker notes are included, since they are already in the deck’s HTML; authoring comments are not, since they are stripped from it. A deck marked published: false or unlisted: true is left out, the same keys a content collection entry uses. This needs astromotion 0.36 or newer, whether the theme registers it for you through decks or your site registers it itself.

Citation

A CITATION.cff at the project root tells readers, human and machine, how to credit the site. When the file exists, every page’s head carries schema.org JSON-LD (the page as part of the cited work, with its authors, ORCIDs, licence and DOI) and a <link rel="cite-as"> to the DOI or URL. With llmsTxt on, /llms.txt gains a “Citing this site” block after its preamble, and every markdown twin and every page in /llms-full.txt ends with its source URL, licence and a formatted citation, so text copied out of context still names where it came from.

Fields under preferred-citation win over the file’s top level, which lets the citation name an issuing institution (preferred-citation.institution) apart from the authors’ own affiliations — a course taught by one school and written by someone employed at another, say:

cff-version: 1.2.0
title: "Example Course (course materials)"
authors:
  - family-names: Example
    given-names: Alex
    affiliation: "School of Design"
    orcid: "https://orcid.org/0000-0000-0000-0000"
doi: 10.5281/zenodo.1234567
license: CC-BY-4.0
preferred-citation:
  type: generic
  title: "Example Course"
  medium: "Course materials"
  authors:
    - family-names: Example
      given-names: Alex
  institution:
    name: "School of Computing"
  doi: 10.5281/zenodo.1234567
  year: 2026

A file elsewhere (the repository root above a website/ directory, say) is named with citation: "../CITATION.cff", which fails the build if the file is missing; citation: false turns the feature off.

Site config

Rather than repeating the same props on every page, create a central config file that exports your site’s identity and navigation. Use the defineSiteConfig helper from astro-theme-university/types — an identity-typed function that gives you autocomplete and type-checking on the full SiteConfig shape:

// src/site-config.ts
import { defineSiteConfig } from "astro-theme-university/types";

export const siteConfig = defineSiteConfig({
  name: "My Research Group",
  links: [
    { text: "Home", href: "/" },
    { text: "About", href: "/about/" },
    { text: "Publications", href: "/publications/" },
  ],
  contact: {
    description: "School of Something, Example University",
    address: "Building 123, Example Road, Canberra ACT 2601",
    email: "enquiries@example.edu",
    phone: "+61 2 6100 0000",
  },
  socials: [
    { platform: "linkedin", url: "https://linkedin.com/company/example" },
  ],
  licence: "CC-BY-4.0",
});

The theme ships no default logo. With no logo prop, the site name renders in the navigation bar as a text wordmark. To show a logo instead, pass an imported image as logo (and optionally logoDark for dark mode). If your logo is a wide horizontal lockup, also pass logoCompact (a crest or monogram) so the nav swaps to it below the 640px breakpoint instead of wrapping — see the Nav docs.

The socials array supports "facebook", "instagram", "youtube", and "linkedin" as platform values.

Passing config to BaseLayout

Spread the site config into BaseLayout on each page, then override anything page-specific:

---
// src/pages/index.astro
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
import { siteConfig } from "../site-config";
---

<BaseLayout title="Home" {...siteConfig}>
  <h1>Welcome</h1>
</BaseLayout>

This pattern means adding a new nav link or changing the site name is a single edit in site-config.ts.

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.