Getting started

Create your repo#

Easiest path — use the GitHub UI:

1. Open astro-docs-template.
2. Click Use this template → Create a new repository.
3. Clone it locally.

Or via the CLI:

gh repo create my-docs --template qwexvf/astro-docs-template --public --clone
cd my-docs

Install#

bun install

Requires Node ≥ 22.12 (Astro 6 needs it).

If you prefer npm or pnpm: delete bun.lock, then npm install or pnpm install. Update the workflow files accordingly.

Run#

bun dev

Open http://localhost:4321. Edits to markdown reload instantly.

Build#

bun build

Output goes to dist/. Pagefind runs after the build and indexes every page into dist/pagefind/.

Deploy to GitHub Pages#

The included workflow does it for you. In your repo:

1. Settings → Pages → Source: GitHub Actions.
2. Push to main.
3. The deploy-pages workflow builds with PUBLIC_BASE=/<repo-name>/ and publishes.

For a custom domain: set site: in astro.config.mjs, drop a CNAME file into public/, and don’t set PUBLIC_BASE.

Deploy elsewhere#

Static output. Anywhere that serves a folder works:

Next#

• Authoring — write your first page.
• Customizing — make it look like yours.