# Deploying

> Deploy an astro-theme-university site to common hosting platforms.

Astro's build output goes into `dist/`, deployable to any static hosting
provider.

## [GitHub Pages](https://pages.github.com/)

The [starter example](https://anucybernetics.github.io/astro-theme-university/docs/getting-started/examples/) ships a ready-made
workflow at `.github/workflows/deploy.yml`; copy it into any site. It provisions
Node and pnpm from the project's `mise.toml`, builds with `SITE_URL` and
`BASE_PATH` derived from the repository name, and publishes `dist/` through the
official Pages actions. (The two `actions/cache` steps for the pnpm store and
Astro's build cache are trimmed here.)

```yaml
# .github/workflows/deploy.yml
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: jdx/mise-action@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
        env:
          SITE_URL: https://${{ github.repository_owner }}.github.io
          BASE_PATH: /${{ github.event.repository.name }}
      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 5
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - id: deploy
        uses: actions/deploy-pages@v5
```

In the repository settings, set Pages → Source to "GitHub Actions" once. A
project site is served at `https://<owner>.github.io/<repo>/`, so `BASE_PATH` is
`/<repo>`; for a user or organisation site (a repository named
`<owner>.github.io`) set it to `/`. The theme's link checker verifies that every
internal link carries the base prefix, so a link that would 404 on the live site
fails the build instead.

## [Cloudflare Pages](https://pages.cloudflare.com/)

Connect your repository in the Cloudflare Pages dashboard, then configure:

- **Build command**: `pnpm build`
- **Build output directory**: `dist`
- **Node.js version**: set the `NODE_VERSION` environment variable to `24` or
  later (the theme's `engines` floor)

## [Netlify](https://www.netlify.com/)

Connect the repository and set:

- **Build command**: `pnpm build`
- **Publish directory**: `dist`

You can also add a `netlify.toml` to your repository:

```toml
[build]
  command = "pnpm build"
  publish = "dist"
```

## Base path configuration

If your site isn't served from the domain root, `astro.config.ts`'s `base`
option prefixes all internal links and asset paths automatically. This applies
to every deployment target, not just GitHub Pages.

```js
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://example.com",
  base: "/docs",
});
```

When `base` is set, use Astro's built-in URL handling rather than hard-coding
paths; `import.meta.env.BASE_URL` gives the base path at runtime.
