Deploy your Doc Site

Learn how to deploy your documentation site to various hosting platforms. We’ll cover deployment to Vercel, Netlify, and GitHub Pages.

Build your Site

Before deploying, build your site locally to ensure everything works:

npm run build

# Using pnpm
pnpm build

# Using yarn
yarn build

This will generate a static site in the dist directory.

Deploy to Vercel

Option 1: Deploy from Git

1. Push your repository to GitHub, GitLab, or Bitbucket
2. Import your project into Vercel
3. Vercel will automatically detect Astro and configure the build settings

Option 2: Deploy from CLI

1. Install the Vercel CLI:

   npm i -g vercel

2. Run the deployment command:

   vercel

Vercel Configuration

Create a vercel.json file in your project root:

{
  "framework": "astro",
  "buildCommand": "pnpm build",
  "devCommand": "pnpm dev",
  "installCommand": "pnpm install"
}

Deploy to Netlify

Option 1: Deploy from Git

1. Push your repository to GitHub, GitLab, or Bitbucket
2. Import your project into Netlify
3. Use these build settings:
   • Build command: pnpm build
   • Publish directory: dist

Option 2: Deploy from CLI

1. Install the Netlify CLI:

   npm i -g netlify-cli

2. Run the deployment command:

   netlify deploy

Netlify Configuration

Create a netlify.toml file in your project root:

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

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Deploy to GitHub Pages

GitHub Actions Setup

1. Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
      
      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Configure Astro

Update your astro.config.ts:

export default defineConfig({
  site: 'https://username.github.io',
  base: '/your-repo-name',
  // ... other config
});

Environment Variables

Production Variables

Set these environment variables in your hosting platform:

SITE_URL=https://your-site.com
NODE_ENV=production

Platform-Specific Settings

Best Practices

1. Before Deployment

   • Run build locally
   • Test all pages
   • Check responsive design
   • Verify all links work

2. Performance

   • Optimize images
   • Enable caching
   • Use CDN for assets
   • Minimize JavaScript

3. SEO

   • Configure meta tags
   • Add robots.txt
   • Create sitemap.xml
   • Set up canonical URLs

4. Monitoring

   • Set up error tracking
   • Monitor performance
   • Check analytics
   • Configure alerts

5. Security

   • Enable HTTPS
   • Set security headers
   • Configure CSP
   • Regular updates

Troubleshooting

Common Issues

1. Build Failures

   • Check Node.js version
   • Verify dependencies
   • Review build logs
   • Check environment variables

2. 404 Errors

   • Verify base path
   • Check routing rules
   • Review redirects
   • Confirm file paths

3. Style Issues

   • Clear cache
   • Check CSS builds
   • Verify Tailwind config
   • Review media queries

Getting Help

• Check the Astro Discord
• Review GitHub Issues
• Consult platform-specific documentation
• Contact support teams