Host your Docusaurus on Vercel - howto

Here's a step-by-step tutorial to host your Docusaurus documentation on Vercel using GitHub, with automatic deployments:

Step 1: Prepare Your Docusaurus Project

1. Install Docusaurus (if not already created):

npx create-docusaurus@latest my-course classic
cd my-course

2. Organize your Markdown files:

# Replace default docs with your course content
rm -rf docs/*
cp -R /path/to/your/md/files/* docs/

3. Configure docusaurus.config.js:

module.exports = {
  title: 'My Online Course',
  url: 'https://your-course.vercel.app',
  baseUrl: '/',
  organizationName: 'your-github-username',
  projectName: 'your-repo-name',
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          routeBasePath: '/', // Serve docs at root
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: false, // Disable blog if not needed
      },
    ],
  ],
};

Step 2: Set Up GitHub Repository

1. Initialize Git:

git init
git add .
git commit -m "Initial course content"

2. Create new GitHub repository at github.com/new

   • Name: your-course-repo

   • Do not initialize with README

3. Push to GitHub:

git remote add origin https://github.com/your-username/your-repo-name.git
git branch -M main
git push -u origin main

Step 3: Deploy to Vercel

1. Sign up at vercel.com using GitHub account

2. Click "Add New Project" > "Import Project"

3. Select your GitHub repository

4. Configure project settings:

   • Project Name: your-course-name

   • Build Command: npm run build

   • Output Directory: build

   • Install Command: npm install

5. Click "Deploy" - First build will start automatically

Step 4: Configure Automatic Deployments

1. Enable GitHub integration:

   • Go to Vercel project > Settings > Git

   • Enable "Automatically deploy on commit"

2. Create vercel.json for custom routing:

{
  "cleanUrls": true,
  "trailingSlash": false,
  "rewrites": [
    { "source": "/(.*)", "destination": "/$1" }
  ]
}

Step 5: Organize Course Structure

1. Edit sidebars.js to create navigation:

module.exports = {
  myCourseSidebar: [
    {
      type: 'category',
      label: 'Module 1: Introduction',
      items: ['intro', 'getting-started'],
    },
    {
      type: 'category',
      label: 'Module 2: Core Concepts',
      items: ['concepts-1', 'concepts-2', 'exercises'],
    },
    // Add more modules...
  ],
};

2. Add metadata to Markdown files:

---
title: Getting Started
sidebar_position: 2
tags: [beginner, setup]
---

Step 6: Add Course Features

1. Install useful plugins:

npm install @docusaurus/theme-live-codeblock @docusaurus/plugin-ideal-image

2. Enable in docusaurus.config.js:

plugins: [
  '@docusaurus/theme-live-codeblock',
  [
    '@docusaurus/plugin-ideal-image',
    { quality: 70, max: 1030 },
  ],
],

Step 7: Custom Domain (Optional)

1. Buy domain from Namecheap/Porkbun

2. In Vercel project:

   • Go to Settings > Domains

   • Enter your domain (e.g., course.yourdomain.com)

   • Configure DNS as instructed:

       CNAME: course → cname.vercel-dns.com
     

Step 8: Update & Maintain

1. Make content changes locally

2. Commit and push to GitHub:

git add .
git commit -m "Updated lesson 3"
git push origin main

Vercel will automatically rebuild and deploy in 30-60 seconds

Troubleshooting Tips

• Build fails: Check logs in Vercel dashboard

• Missing content: Verify file paths in sidebars.js

• Broken links: Run npx docusaurus check-links

• Performance issues: Add caching headers in vercel.json:

    "headers": [
      {
        "source": "/(.*)",
        "headers": [
          { "key": "Cache-Control", "value": "public, max-age=3600" }
        ]
      }
    ]
  

Final Structure

my-course/
├── docs/
│   ├── module1/
│   │   ├── lesson1.md
│   │   └── lesson2.md
│   └── module2/
├── src/
│   └── css/
│       └── custom.css
├── static/
│   └── images/
├── docusaurus.config.js
├── sidebars.js
├── vercel.json
└── package.json

Access your course: https://your-course.vercel.app
Admin dashboard: https://vercel.com/your-username/your-project

Need professional optimization? Our team can enhance your course with quizzes, analytics, and LMS integration - Book a free consultation