# Installation

> Install astro-theme-university and its peer dependencies, configure the integration, and create your first page.

The quickest way to a working site is to
[copy the starter example](https://anucybernetics.github.io/astro-theme-university/docs/getting-started/examples/), which has all of
this done. This page is the manual route: adding the theme to a project you
create yourself, or to an existing Astro project.

## Create the project

The theme isn't published to npm; it's installed straight from a tagged release
of its public Git repository, with pnpm. Start with a `package.json` that
declares the project as an ES module and gives you the usual Astro scripts:

```json
{
  "name": "my-site",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "typecheck": "astro check"
  }
}
```

Next to it, a `pnpm-workspace.yaml` that tells pnpm which install scripts may
run. Without it, the first install stops with "Ignored build scripts":

```yaml
allowBuilds:
  esbuild: true
  sharp: false
```

`esbuild` needs its postinstall to fetch the platform-specific binary. `sharp`
is set to `false` because its install script falls through to a from-source
build when a system `libvips` is present (macOS with Homebrew, for instance),
and the prebuilt `@img/sharp-*` platform binary works at runtime regardless.

## Install the package

Find the latest tag on the
[tags page](https://github.com/ANUcybernetics/astro-theme-university/tags) and
pin it exactly. Install it alongside the required peer dependencies:

```bash
pnpm add astro "git+https://github.com/ANUcybernetics/astro-theme-university.git#vX.Y.Z" @astrojs/mdx sharp pagefind lightningcss @iconify-json/iconoir
pnpm add -D @astrojs/check "typescript@^6"
```

The theme requires Astro ^7.0.0. `@astrojs/mdx` is needed so Astro can resolve
the renderer entry point from your project root; the theme auto-registers the
integration at build time. `lightningcss` is required because the theme
configures Vite's CSS transformer to use it; Vite resolves that package from
your project root, not from inside the theme. `@iconify-json/iconoir` ships the
iconoir icon set; `astro-icon` resolves iconify-set packages from the consumer's
`package.json` (not the theme's), so the set has to live as a direct dep.
`pagefind` builds the on-site search index after each build; search is on by
default and the build fails if the binary is missing, so it's only optional if
you pass `search: false`. `sharp` is Astro's image service, which the theme's
`Card` and `Hero` components use to encode local images. The theme's interactive
controls use native browser APIs and add no UI-framework dependency.

`@astrojs/check` and `typescript` are what `pnpm typecheck` runs. TypeScript
stays on 6.x for now: `astro check` relies on a programmatic API the native
TypeScript 7 compiler doesn't ship yet.

Upgrading later is a deliberate edit: change the tag in `package.json` and run
`pnpm install`. pnpm never moves a git dependency on its own, which is what
makes an exact tag a reproducible pin.

## Add the integration

Register the theme integration in your Astro config:

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

export default defineConfig({
  site: process.env.SITE_URL,
  base: process.env.BASE_PATH,
  integrations: [universityTheme()],
});
```

The theme integration automatically:

- registers `@astrojs/mdx` (set `mdx: false` to opt out)
- registers `astro-icon` for the theme's `Icon` component (set `icon: false` to
  opt out)
- adds Google font providers for Public Sans and Roboto Mono with the theme's
  CSS variable names (set `fonts: false` to opt out)
- configures [Lightning CSS](https://lightningcss.dev/) as the CSS transformer
- wires up remark/rehype plugins for callouts, heading IDs, autolinked headings,
  and smart typography
- builds a Pagefind search index after each build (set `search: false` to opt
  out)
- runs broken-link and axe-core accessibility checks, with optional `/llms.txt`
  generation
- registers astromotion for slide decks when `decks` is set (see
  [lecture decks](https://anucybernetics.github.io/astro-theme-university/docs/guides/lecture-decks/))

The theme is framework-free. If you're coming from an older template that
installed Svelte only for the theme, remove `svelte`, `@astrojs/svelte`,
`svelte-check`, and the explicit `svelte()` integration; keep a framework only
when your own components use it.

## Create your first page

Add a `tsconfig.json` that extends Astro's strict preset (this is what resolves
imports like `astro-theme-university/layouts/BaseLayout.astro`):

```json
{
  "extends": "astro/tsconfigs/strict"
}
```

Then use the theme's `BaseLayout` in any Astro page:

```astro
---
// src/pages/index.astro
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
---

<BaseLayout title="My site">
  <h1>Welcome</h1>
  <p>This page uses the theme's BaseLayout.</p>
</BaseLayout>
```

`pnpm build` produces a static site in `dist/` after running the accessibility
and link checks.

The next step is to [configure your site](https://anucybernetics.github.io/astro-theme-university/docs/getting-started/configuration/)
with a name and navigation links.
