Deploying Slidev Presentations

This skill covers deploying Slidev presentations as static websites to various hosting platforms, making your presentations accessible online.

When to Use This Skill

Sharing presentations via URL
Hosting for conferences/events
Creating permanent presentation archives
Setting up CI/CD for presentations
Embedding presentations in websites

Building for Production

Build Command

npx slidev build

Or via npm script:

npm run build

Output

Creates dist/ directory containing:

index.html
JavaScript bundles
CSS files
Asset files

Build Options

# Custom output directory
npx slidev build --out public

# With base path (for subdirectories)
npx slidev build --base /presentations/my-talk/

# Enable PDF download
npx slidev build --download

# Exclude presenter notes (security)
npx slidev build --without-notes

GitHub Pages

Method 1: GitHub Actions (Recommended)

Enable GitHub Pages:
- Go to Settings → Pages
- Source: GitHub Actions
Create workflow file .github/workflows/deploy.yml:

name: Deploy Slidev

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build -- --base /${{ github.event.repository.name }}/

      - 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

Push to trigger deployment
Access at: https://<username>.github.io/<repo>/

Method 2: gh-pages Branch

npm install -D gh-pages

Add to package.json:

{
  "scripts": {
    "deploy": "slidev build --base /repo-name/ && gh-pages -d dist"
  }
}

Then:

npm run deploy

Netlify

Method 1: Netlify UI

Push code to GitHub/GitLab
Connect repo in Netlify dashboard
Configure:
- Build command: npm run build
- Publish directory: dist

Method 2: netlify.toml

Create netlify.toml:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

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

Push and Netlify auto-deploys.

Custom Domain

In Netlify dashboard:

Domain settings
Add custom domain
Configure DNS

Vercel

Method 1: Vercel CLI

npm install -g vercel
vercel

Method 2: vercel.json

Create vercel.json:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": null,
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Automatic Deployment

Import project in Vercel dashboard
Connect GitHub repo
Vercel auto-detects and deploys

Cloudflare Pages

Setup

Connect repo in Cloudflare Pages
Configure:
- Build command: npm run build
- Output directory: dist
Deploy

wrangler.toml (Optional)

name = "my-presentation"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist"

Docker

Dockerfile

FROM node:20-alpine as builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

nginx.conf

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    server {
        listen 80;
        server_name localhost;
        root /usr/share/nginx/html;
        index index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

Build and Run

docker build -t my-presentation .
docker run -p 8080:80 my-presentation

Docker Compose

version: '3.8'
services:
  presentation:
    build: .
    ports:
      - "8080:80"
    restart: unless-stopped

Self-Hosted (Static Server)

Using serve

npm install -g serve
npm run build
serve dist

Using http-server

npm install -g http-server
npm run build
http-server dist

Using Python

npm run build
cd dist
python -m http.server 8080

Base Path Configuration

For Subdirectories

If hosting at https://example.com/slides/:

npx slidev build --base /slides/

Or in frontmatter:

---
base: /slides/
---

Root Path

If hosting at root https://example.com/:

npx slidev build --base /

Security Considerations

Excluding Presenter Notes

npx slidev build --without-notes

Removes speaker notes from built version.

Password Protection

For private presentations:

Netlify: Use Netlify Identity or password protection feature.

Vercel: Use Vercel Authentication.

Custom: Add basic auth in server config.

No Remote Control in Build

Built presentations don't include remote control by default.

Environment Variables

In Build

Create .env:

VITE_API_URL=https://api.example.com

Access in slides:

<script setup>
const apiUrl = import.meta.env.VITE_API_URL
</script>

Platform-Specific

Set in platform dashboards (Netlify, Vercel, etc.)

Custom Domain Setup

DNS Configuration

Type	Name	Value
CNAME	www	platform-subdomain
A	@	Platform IP

SSL/HTTPS

Most platforms provide free SSL:

Netlify: Automatic
Vercel: Automatic
Cloudflare: Automatic
GitHub Pages: Automatic

CI/CD Workflows

GitHub Actions (Full Example)

name: Build and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install
        run: npm ci

      - name: Build
        run: npm run build

      - name: Export PDF
        run: npm run export

      - name: Upload Build
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

      - name: Upload PDF
        uses: actions/upload-artifact@v4
        with:
          name: pdf
          path: '*.pdf'

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Download Build
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - name: Deploy to Production
        # Add your deployment step

Troubleshooting

Build Fails

Check Node version (≥18)
Clear node_modules: rm -rf node_modules && npm install
Check for syntax errors in slides

Assets Not Loading

Verify base path configuration
Check asset paths (use / prefix for public/)
Rebuild with correct base

Fonts Missing

Use web fonts
Check font loading in styles

Blank Page After Deploy

Check browser console for errors
Verify SPA routing configuration
Check base path matches URL

Best Practices

Test Build Locally:
```
npm run build && npx serve dist
```
Use CI/CD: Automate deployments
Version Your Deployments: Use git tags
Monitor Performance: Check load times
Keep URLs Stable: Don't change paths frequently

Output Format

When deploying:

PLATFORM: [GitHub Pages | Netlify | Vercel | Docker]

BUILD COMMAND:
npm run build --base [path]

CONFIGURATION FILES:
- [config file name and content]

DEPLOYMENT URL:
https://[your-domain]/[path]/

CHECKLIST:
- [ ] Build succeeds locally
- [ ] Assets load correctly
- [ ] Base path configured
- [ ] SSL/HTTPS enabled
- [ ] (Optional) Custom domain
- [ ] (Optional) Password protection

slidev-deployment