Deployment

• a prerendered index.html for every page
• sitemap.xml (when the production site URL is set)
• redirect pages for every redirects rule
• a .md copy of every page for AI tools
• 404.html for hosts that serve it on unknown paths

GitHub Pages#

Point Pages at the build output with an action:

name: Deploy docs
 
on:
  push:
    branches: [main]
 
permissions:
  contents: read
  pages: write
  id-token: write
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # full history for last-modified timestamps
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/client
      - uses: actions/deploy-pages@v4

GitHub Pages serves 404.html for unknown paths automatically, so client-side routing keeps working on deep links.

Netlify#

• Build command: pnpm build
• Publish directory: dist/client

Vercel#

The repository includes vercel.json, which configures the build command (pnpm build), framework preset (Other), and output directory (dist/client). Shiso prerenders its own routes, so Vercel serves it as a static site rather than applying generic Vite SPA routing.

Cloudflare Pages#

• Build command: pnpm build
• Build output directory: dist/client

Deploying under a subpath#

When the site lives at https://example.com/my-docs/ rather than a domain root, pass the base path to shiso build:

{
  "build": "shiso build --base=/my-docs/"
}

The prerenderer detects the base from the build output and lays out the directories to match.

Checklist#

• Set the production site URL so canonical URLs, Open Graph tags, and the sitemap are emitted
• Use a full-history checkout if last-modified timestamps are enabled
• Verify a deep link (any docs page URL) after the first deploy

Back to Introduction.