# 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):
    

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

2. Organize your Markdown files:
    

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

3. Configure `docusaurus.config.js`:
    

```javascript
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:
    

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

2. Create new GitHub repository at [github.com/new](http://github.com/new)
    
    * Name: `your-course-repo`
        
    * **Do not** initialize with README
        
3. Push to GitHub:
    

```bash
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](http://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`
        
    
    ![Vercel settings](https://vercel.com/docs/static/configure/overview.png align="left")
    
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:
    

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

### Step 5: Organize Course Structure

1. Edit `sidebars.js` to create navigation:
    

```javascript
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:
    

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

### Step 6: Add Course Features

1. Install useful plugins:
    

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

2. Enable in `docusaurus.config.js`:
    

```javascript
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`](http://course.yourdomain.com))
        
    * Configure DNS as instructed:
        
        ```plaintext
        CNAME: course → cname.vercel-dns.com
        ```
        

### Step 8: Update & Maintain

1. Make content changes locally
    
2. Commit and push to GitHub:
    

```bash
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`:
    
    ```json
    "headers": [
      {
        "source": "/(.*)",
        "headers": [
          { "key": "Cache-Control", "value": "public, max-age=3600" }
        ]
      }
    ]
    ```
    

### Final Structure

```plaintext
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**](https://your-course.vercel.appAdmin) **dashboard:** [`https://vercel.com/your-username/your-project`](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](https://tenten.co/contact)