Deploy Docusaurus for Documentation Sites

Docusaurus is Meta's open-source documentation framework that makes it easy to build, deploy, and maintain beautiful documentation websites. Built on React, it supports Markdown/MDX, versioning, search, and i18n out of the box. This guide covers deploying Docusaurus on your VPS for production documentation sites.

Create a Docusaurus Project

# Create new Docusaurus site
npx create-docusaurus@latest my-docs classic --typescript
cd my-docs

# Project structure
my-docs/
├── docs/              # Documentation pages (Markdown/MDX)
│   ├── intro.md
│   ├── tutorial-basics/
│   └── tutorial-extras/
├── blog/              # Blog posts
├── src/
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Custom pages
├── static/            # Static assets
├── docusaurus.config.ts
├── sidebars.ts
└── package.json

Configure for Your Project

// docusaurus.config.ts
import { themes as prismThemes } from 'prism-react-renderer'
import type { Config } from '@docusaurus/types'

const config: Config = {
  title: 'My Project Docs',
  tagline: 'Documentation for My Project',
  favicon: 'img/favicon.ico',
  url: 'https://docs.yourdomain.com',
  baseUrl: '/',
  organizationName: 'your-org',
  projectName: 'my-project',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  themeConfig: {
    navbar: {
      title: 'My Project',
      logo: { alt: 'Logo', src: 'img/logo.svg' },
      items: [
        { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: 'Docs' },
        { to: '/blog', label: 'Blog' },
        { to: '/api', label: 'API Reference' },
        { type: 'docsVersionDropdown' },
        { href: 'https://github.com/your-org/my-project', label: 'GitHub' },
      ],
    },
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'my-docs',
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['bash', 'nginx', 'yaml', 'docker', 'php'],
    },
  },

  presets: [
    ['classic', {
      docs: {
        sidebarPath: './sidebars.ts',
        editUrl: 'https://github.com/your-org/my-project/edit/main/',
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
      },
      blog: { showReadingTime: true },
      theme: { customCss: './src/css/custom.css' },
    }],
  ],
}
export default config

Writing Documentation

# docs/getting-started/installation.md
---
sidebar_position: 1
title: Installation
description: How to install and configure My Project
tags: [getting-started, installation]
---

# Installation

## Prerequisites

Before installing, ensure you have:

- **Node.js** 18 or higher
- **npm** or **pnpm**

## Quick Start

```bash
npm install my-project
npx my-project init
```

:::tip
Use `pnpm` for faster installations and better disk usage.
:::

:::warning
Version 3.x requires Node.js 18+. Upgrade before installing.
:::

## Configuration

Create a `config.yaml` in your project root:

```yaml title="config.yaml"
project:
  name: my-app
  environment: production
  port: 3000
```

Build and Deploy

# Build static site
npm run build

# Output is in the 'build' directory
ls build/

# Deploy with Nginx
sudo mkdir -p /var/www/docs
sudo cp -r build/* /var/www/docs/

# Nginx configuration
cat > /etc/nginx/sites-available/docs