Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facebook/docusaurus/llms.txt

Use this file to discover all available pages before exploring further.

Docusaurus generates a folder of static files that can be hosted anywhere a web server can serve HTML. After running the build command, you copy the output to your host of choice — Docusaurus itself has no runtime server-side component.

​
Build the site

Before deploying, compile your source files into static output: 
npm run build
The generated files land in build/. You can verify the output locally before uploading: 
npm run serve
This serves build/ at http://localhost:3000 and is the closest approximation of production you can run on your machine.
Make sure url and baseUrl in docusaurus.config.js match your deployment target before building. Incorrect values cause broken asset paths and wrong canonical URLs.

​
Required config fields

Two fields in docusaurus.config.js must be correct for your host:
FieldDescription
urlThe root of your site, without a trailing slash. For https://my-org.com/my-project/, this is https://my-org.com.
baseUrlThe path prefix, with a trailing slash. For the same site, this is /my-project/. For a domain root, use '/'.

​
Deployment targets

GitHub Pages is free for all public repositories and is built into every GitHub account. The docusaurus deploy command automates the entire process: it builds the site and pushes the output to the deployment branch in one step.
1

Configure docusaurus.config.js

Add the three required fields for GitHub Pages deployment:
docusaurus.config.js
export default {
  url: 'https://my-org.github.io',
  baseUrl: '/my-project/',
  organizationName: 'my-org',   // GitHub org or username
  projectName: 'my-project',    // Repository name
  trailingSlash: false,
};
For an organization root site (repo named my-org.github.io), use baseUrl: '/' and omit projectName or set it to the repo name.
2

Prevent Jekyll processing

GitHub Pages runs files through Jekyll by default, which strips files whose names begin with _. Add an empty .nojekyll file to your static/ directory to disable this:
touch static/.nojekyll
3

Run the deploy command

Set GIT_USER to your GitHub username, then run:
GIT_USER=<your-github-username> yarn deploy
The command clones the repo, builds the site, commits the output to the gh-pages branch, and pushes.
GitHub requires a personal access token (PAT) instead of a password for command-line authentication. When prompted for a password, enter your PAT. Alternatively, set USE_SSH=true to authenticate over SSH instead.
4

Automate with GitHub Actions (optional)

Add this workflow file to trigger a deployment on every push to main:
.github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build
      - name: Upload build artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
Also add a test workflow for pull requests to catch broken builds before merge:
.github/workflows/test-deploy.yml
name: Test deployment

on:
  pull_request:
    branches:
      - main

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - name: Install dependencies
        run: npm ci
      - name: Test build website
        run: npm run build

​
Choosing a deployment target

GitHub Pages

Free for public repos. Straightforward if your code is already on GitHub. The docusaurus deploy command and the GitHub Actions workflow handle everything automatically.

Netlify

Easiest setup overall. Generous free tier, automatic preview URLs for pull requests, and one-click rollbacks. Best for teams who want zero infrastructure work.

Vercel

Excellent performance and developer experience. Auto-detects Docusaurus. Preview deployments and edge caching on the free plan.

Self-hosted

Full control over server configuration, redirects, authentication, and custom middleware. Most complex to maintain, but the only option when data cannot leave your infrastructure.

​
Environment variables in builds

docusaurus.config.js is the only file that runs in Node.js during the build — MDX pages and React components are client-side and cannot read process.env directly. Pass environment variables through customFields:
docusaurus.config.js
import 'dotenv/config';

export default {
  url: process.env.SITE_URL,
  customFields: {
    apiEndpoint: process.env.API_ENDPOINT,
  },
};
src/pages/index.jsx
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function Home() {
  const {siteConfig: {customFields}} = useDocusaurusContext();
  return <p>API: {customFields.apiEndpoint}</p>;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us