Astro’s build output goes into dist/, deployable to any static hosting
provider.
GitHub Pages#
The starter example 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.)
# .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#
Connect your repository in the Cloudflare Pages dashboard, then configure:
- Build command:
pnpm build - Build output directory:
dist - Node.js version: set the
NODE_VERSIONenvironment variable to24or later (the theme’senginesfloor)
Netlify#
Connect the repository and set:
- Build command:
pnpm build - Publish directory:
dist
You can also add a netlify.toml to your repository:
[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.
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.