Skip to main content

Project setup

Directory structure

A typical site using the theme looks like this:

my-site/
├── astro.config.ts
├── package.json
├── tsconfig.json
└── src/
    ├── site-config.ts
    ├── assets/
    │   └── images/
    │       └── favicon.svg   # imported in site-config.ts
    ├── pages/
    │   ├── index.astro
    │   └── about.astro
    ├── content.config.ts     # if using content collections
    ├── content/
    │   └── posts/
    │       └── first-post.md
    └── styles/
        └── custom.css  # any project-specific overrides

The theme provides layouts, components, base styles, and assets — your project supplies the pages and content that use them.

TypeScript configuration

Astro projects should extend the framework’s built-in TypeScript config. A minimal tsconfig.json:

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

This gives you path resolution for theme imports like astro-theme-university/components/Callout.astro without any extra aliases.

CSS and Lightning CSS

The theme integration registers Lightning CSS as the Vite CSS transformer automatically, so you don’t need to configure it. This enables modern CSS features — nesting, custom media queries, and colour functions — with broad browser support.

If you add your own stylesheets, import them in your pages or layouts as usual. The theme’s styles use @layer to keep specificity predictable, so your overrides will take effect without fighting the cascade.

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

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

Creating pages

Each .astro file in src/pages/ becomes a route. Import BaseLayout and your site config, then write your content in the slot.

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

<BaseLayout title="About" {...siteConfig}>
  <h1>About us</h1>
  <p>We are a research group at Example University.</p>
</BaseLayout>

You can also use theme components within your pages:

---
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
import Callout from "astro-theme-university/components/Callout.astro";
import { siteConfig } from "../site-config";
---

<BaseLayout title="Research" {...siteConfig}>
  <h1>Our research</h1>
  <Callout type="info">
    Applications for the 2026 intake are now open.
  </Callout>
</BaseLayout>

Content collections

For blog posts, docs pages, or other structured content, use Astro’s content collections. The theme ships a definePageCollection helper that wraps defineCollection + glob + a page-style Zod schema (title, description, heroImage, published), so a typical src/content.config.ts is a few lines:

// src/content.config.ts
import { definePageCollection } from "astro-theme-university/schemas";

const pages = definePageCollection();
export const collections = { pages };

See content collections for extending the base schema with custom fields, and for the defineCollection fallback path if you need a different shape.

The theme is developed with oxlint and oxfmt for linting and formatting. For a consistent setup:

These are optional — the theme works without any of them.