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