# Configuration

> Configure theme options, create a site config file, and pass settings to the BaseLayout.

## Theme options

The `universityTheme()` integration accepts an optional configuration object.

```js
// 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,
    }),
  ],
});
```

<PropsTable component="ThemeOptions" />

`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](https://anucybernetics.github.io/astro-theme-university/docs/guides/markdown-extensions#base-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:

```js
// astro.config.ts
universityTheme({ defaultLayout: "src/layouts/PageLayout.astro" });
```

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

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

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

```markdown
# 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](https://anucybernetics.github.io/astro-theme-university/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:

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

```yaml
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 {#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:

```ts
// 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",
});
```

:::info

Import `defineSiteConfig` from `astro-theme-university/types` (the types-only
subpath), **not** from `astro-theme-university` directly. The subpath keeps your
site-config module lightweight and avoids pulling the theme's integration code
into your page bundles.

:::

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](https://anucybernetics.github.io/astro-theme-university/docs/components/nav/).

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:

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

<PropsTable component="layouts/BaseLayout" />
