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.
Recommended tooling#
The theme is developed with oxlint and oxfmt for linting and formatting. For a consistent setup:
- oxlint for fast JavaScript/TypeScript linting
- oxfmt for fast formatting
across
.ts,.js,.json,.md, and.cssfiles - stylelint for CSS linting
These are optional — the theme works without any of them.