Building and Deploying

Building and Deploying

Overview

Once your documentation is written, you need to build it and deploy it to a hosting platform. This section covers the build process and deployment to the most popular free hosting platforms.

Q&A

Q: How do I build the site?

A: Run the build command:

npm run build

This generates a static site in the dist/ directory. Astro:

1. Processes all Markdown/MDX files
2. Generates HTML pages with syntax highlighting
3. Creates a sitemap (sitemap-index.xml)
4. Builds the search index (Pagefind)
5. Optimizes CSS and JavaScript

To preview the build locally:

npm run preview

Q: Which hosting platforms are recommended?

A: For static documentation sites, these platforms offer free hosting with excellent performance:

Platform	Free Tier	Custom Domain	Auto Deploy	Best For
Vercel	Generous	Yes	GitHub/GitLab	Astro projects (native support)
Cloudflare Pages	Unlimited	Yes	GitHub/GitLab	Global CDN, no bandwidth limits
GitHub Pages	1GB storage	Yes	GitHub only	Simple projects, open source
Netlify	100GB bandwidth	Yes	GitHub/GitLab	Form handling, edge functions

Q: How do I deploy to Vercel?

A: Vercel has first-class Astro support:

1. Connect your repository:

   • Go to vercel.com and sign in with GitHub
   • Click “New Project” and import your repository

2. Configure the project:

   • Framework Preset: Astro
   • Build Command: npm run build
   • Output Directory: dist

3. Deploy: Click “Deploy” and Vercel will build and publish your site

Every push to main triggers an automatic redeployment. Pull requests get preview URLs.

Alternatively, use the Vercel CLI:

npm install -g vercel
vercel --prod

Q: How do I deploy to GitHub Pages?

A: For GitHub Pages, you need to adjust the astro.config.mjs:

export default defineConfig({
  site: 'https://yourusername.github.io',
  base: '/repo-name',  // Required for GitHub Pages
  integrations: [starlight({ /* ... */ })],
});

Then add a GitHub Actions workflow (.github/workflows/deploy.yml):

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Enable GitHub Pages in repository Settings → Pages → Source: GitHub Actions.

Q: How do I set up a custom domain?

A: Most hosting platforms supports custom domains:

1. Add the domain in your hosting platform’s dashboard (e.g., Vercel → Project Settings → Domains)
2. Configure DNS records at your domain registrar:

Record Type	Name	Value
A	@	76.76.21.21 (Vercel)
CNAME	www	cname.vercel-dns.com
CNAME	docs	cname.vercel-dns.com

3. Wait for propagation (usually 5-30 minutes)
4. HTTPS is automatically configured by most platforms

Q: What about deployment for China-based users?

A: For users in China, consider these hosting options:

• Cloudflare Pages: Good CDN coverage including Asia
• Alibaba Cloud OSS + CDN: Best performance within mainland China (requires ICP filing)
• Tencent Cloud COS + CDN: Alternative to Alibaba (also requires ICP filing)

Note: Vercel and GitHub Pages may be slow or unreliable from mainland China. If your audience is primarily Chinese, a domestic hosting solution with proper ICP filing is recommended.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →