1[build]
2  command = "npm run build:export"
3  publish = "out"
4 
5[build.environment]
6  NODE_VERSION = "20"
7 
8[[redirects]]
9  from = "/*"
10  to = "/index.html"
11  status = 200

This tells Netlify how to build and what to publish.

1npm install -g netlify-cli
2netlify deploy --prod

MEILISEARCH_HOST=https://search.example.com
MEILISEARCH_API_KEY=your-search-key
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

1. Go to Domain settings
2. Click "Add custom domain"
3. Enter your domain (e.g., docs.example.com)
4. Click "Verify"

Option 1: Use Netlify DNS (Recommended)

• Point your domain's nameservers to Netlify
• Netlify manages all DNS records
• Automatic SSL certificate

Option 2: Use External DNS

For subdomain:

Type: CNAME
Name: docs
Value: your-site.netlify.app

For apex domain:

Type: A
Name: @
Value: 75.2.60.5

Check Domain settings → HTTPS for status.

Deploy Previews

Netlify creates preview deployments for every pull request:

What you get:

• Unique URL for each PR
• Automatic updates when you push
• Deploy preview link in PR comments
• Perfect for reviewing changes

Configure Deploy Previews

Control when previews are created:

1[context.deploy-preview]
2  command = "npm run build:export"
3 
4[context.branch-deploy]
5  command = "npm run build:export"

Advanced Features

Redirect Rules

Add redirects in netlify.toml:

1# Redirect old URLs
2[[redirects]]
3  from = "/old-page"
4  to = "/new-page"
5  status = 301
6 
7# SPA fallback
8[[redirects]]
9  from = "/*"
10  to = "/index.html"
11  status = 200
12 
13# Country-based redirects
14[[redirects]]
15  from = "/docs"
16  to = "/en/docs"
17  status = 302
18  conditions = {Country = ["US"]}

Headers

Add custom headers:

1[[headers]]
2  for = "/*"
3  [headers.values]
4    X-Frame-Options = "DENY"
5    X-XSS-Protection = "1; mode=block"
6    Content-Security-Policy = "default-src 'self'"
7 
8[[headers]]
9  for = "/assets/*"
10  [headers.values]
11    Cache-Control = "public, max-age=31536000, immutable"

Edge Functions

Run code at the edge for dynamic functionality:

Create netlify/edge-functions/hello.ts:

1export default async (request: Request) => {
2  return new Response("Hello from the edge!")
3}
4 
5export const config = {
6  path: "/api/hello"
7}

Split Testing

Test different versions of your docs:

1. Go to Split testing
2. Click "Start a test"
3. Select branches to compare
4. Set traffic split (e.g., 50/50)

Great for testing new documentation layouts or content.

Build Plugins

Extend your build with Netlify plugins:

1[[plugins]]
2  package = "@netlify/plugin-lighthouse"
3 
4[[plugins]]
5  package = "netlify-plugin-checklinks"

Install plugins:

1npm install -D @netlify/plugin-lighthouse netlify-plugin-checklinks

Deployment Contexts

Different configs for different branches:

1# Production (main branch)
2[context.production]
3  command = "npm run build:export"
4  [context.production.environment]
5    NODE_ENV = "production"
6 
7# Staging branch
8[context.staging]
9  command = "npm run build:export"
10  [context.staging.environment]
11    NODE_ENV = "staging"
12 
13# Deploy previews (PRs)
14[context.deploy-preview]
15  command = "npm run build:export -- --debug"

Performance Optimization

Asset Optimization

Netlify automatically optimizes:

• Image compression
• Bundle minification
• Brotli compression

Enable in Build & deploy → Post processing.

Caching

Configure cache headers:

1[[headers]]
2  for = "/_app/immutable/*"
3  [headers.values]
4    Cache-Control = "public, max-age=31536000, immutable"
5 
6[[headers]]
7  for = "/images/*"
8  [headers.values]
9    Cache-Control = "public, max-age=604800"

Prerendering

For better SEO, enable prerendering:

1[[plugins]]
2  package = "@sveltejs/adapter-netlify"

Forms

Add forms to your documentation:

1<form name="contact" method="POST" data-netlify="true">
2  <input type="text" name="name" />
3  <input type="email" name="email" />
4  <textarea name="message"></textarea>
5  <button type="submit">Send</button>
6</form>

Netlify automatically handles form submissions. View responses in Forms tab.

Analytics

Enable Netlify Analytics for visitor insights:

1. Go to Analytics tab
2. Click "Enable Analytics"
3. Costs $9/month (optional)

Shows:

• Page views
• Top pages
• Traffic sources
• Geographic data

CI/CD Integration

GitHub Actions + Netlify

Deploy from GitHub Actions for more control:

1name: Deploy to Netlify
2 
3on:
4  push:
5    branches: [main]
6 
7jobs:
8  deploy:
9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v4
12 
13      - name: Setup Node
14        uses: actions/setup-node@v4
15        with:
16          node-version: '20'
17 
18      - name: Install dependencies
19        run: npm ci
20 
21      - name: Build
22        run: npm run build:export
23 
24      - name: Deploy to Netlify
25        uses: nwtgck/actions-netlify@v2
26        with:
27          publish-dir: './out'
28          production-deploy: true
29        env:
30          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
31          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Get your auth token and site ID from Netlify dashboard.

Troubleshooting

Build Fails

Check build logs:

• Go to Deploys
• Click failed deploy
• View deploy log

Common issues:

• Node version mismatch (set in netlify.toml)
• Missing dependencies (use npm ci not npm install)
• Environment variables not set

Assets 404

Ensure netlify.toml has the SPA redirect:

1[[redirects]]
2  from = "/*"
3  to = "/index.html"
4  status = 200

Functions Not Working

Check function logs:

1. Go to Functions tab
2. Click your function
3. View logs

Ensure function path matches config:

1export const config = {
2  path: "/api/hello"  // Must match your route
3}

Custom Domain SSL Issues

• Wait 24 hours for DNS propagation
• Verify DNS records with dig or nslookup
• Check HTTPS status in Domain settings
• Try re-provisioning certificate

Rollbacks

Instantly rollback to a previous deployment:

1. Go to Deploys
2. Find the working version
3. Click "Publish deploy"

Your site reverts immediately. No waiting for builds.

Monitoring

Deploy Notifications

Get notified when deploys succeed or fail:

1. Go to Site settings → Build & deploy → Deploy notifications
2. Add notification (Email, Slack, webhook)
3. Choose events (deploy started, succeeded, failed)

Status Badge

Add a deploy status badge to your README:

1[![Netlify Status](https://api.netlify.com/api/v1/badges/SITE_ID/deploy-status)](https://app.netlify.com/sites/SITE_NAME/deploys)

Pricing

Netlify's free tier includes:

• 300 build minutes/month
• 100GB bandwidth/month
• Unlimited sites
• Deploy previews
• HTTPS
• Forms (100 submissions/month)

Upgrade to Pro ($19/month) for:

• More bandwidth and build minutes
• Analytics
• Team collaboration
• Priority support

Best Practices

Use netlify.toml - Version control your build config

Enable deploy previews - Review changes before merging

Set up notifications - Know immediately when deploys fail

Use environment variables - Keep secrets out of code

Configure redirects - Handle URL changes properly

Monitor analytics - Understand how users navigate your docs

Test locally - Run npm run build:export && npx serve out first

Next Steps