The quickest way to a working site is to copy the starter example, 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:
{
"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”:
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 and pin it exactly. Install it alongside the required peer dependencies:
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:
// 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(setmdx: falseto opt out) - registers
astro-iconfor the theme’sIconcomponent (seticon: falseto opt out) - adds Google font providers for Public Sans and Roboto Mono with the theme’s
CSS variable names (set
fonts: falseto opt out) - configures Lightning CSS 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: falseto opt out) - runs broken-link and axe-core accessibility checks, with optional
/llms.txtgeneration - registers astromotion for slide decks when
decksis set (see 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):
{
"extends": "astro/tsconfigs/strict"
}
Then use the theme’s BaseLayout in any Astro page:
---
// 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 with a name and navigation links.