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