# Docusaurus Documentation Site

> Modern documentation site with Docusaurus, search, and versioning.

- Category: Development Tools
- Difficulty: beginner
- Components: docusaurus, algolia-docsearch, nginx
- Tags: docusaurus, documentation, react, mdx, static-site
- Source: https://docker.recipes/development/docusaurus-docs

## Overview

Docusaurus is a modern static site generator built by Facebook (Meta) specifically for creating documentation websites. It combines React components with Markdown content, enabling rich interactive documentation with features like versioning, internationalization, and theme customization. Originally developed to power Facebook's open-source project documentation, Docusaurus has become a leading choice for technical documentation due to its developer-friendly approach and extensive plugin ecosystem.

This Docker stack combines Docusaurus with NGINX to create a complete documentation deployment pipeline. The Node.js Alpine container handles both development with hot-reload capabilities and production builds, while NGINX serves the generated static files with optimal performance and caching. The configuration supports both development workflows and production deployments through Docker Compose profiles, eliminating the need for separate deployment configurations.

Development teams, open-source maintainers, and technical writers will find this stack particularly valuable for creating professional documentation sites. The combination provides the flexibility of React-based customization during development with the performance and reliability of NGINX for production serving, making it ideal for everything from API documentation to comprehensive user guides.

## Features

- MDX support allowing React components directly in Markdown content for interactive documentation
- Built-in versioning system to maintain multiple documentation versions simultaneously
- Hot-reload development server with instant preview of content and styling changes
- Algolia DocSearch integration for powerful full-text search across documentation
- NGINX static file serving with optimized caching headers for fast page loads
- Automated sidebar generation based on file structure and frontmatter configuration
- Theme customization through CSS variables and React component swizzling
- Plugin architecture supporting blog functionality, analytics, and third-party integrations

## Use cases

- Open-source project documentation with community contributions via Git workflows
- API documentation sites combining generated references with hand-written guides
- Internal company knowledge bases requiring search and version control
- Product documentation for SaaS platforms with user-facing help centers
- Technical blog platforms combining articles with structured documentation
- Educational content platforms teaching programming concepts with interactive examples
- Software team wikis requiring collaborative editing and professional presentation

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for Node.js builds
- Port 3000 available for development server and port 80 for production NGINX serving
- Basic understanding of Markdown syntax and React concepts for content creation
- Git repository structure for managing documentation source files and versions
- Node.js package.json file with Docusaurus dependencies in the ./docs directory
- Algolia DocSearch API keys if implementing search functionality

## docker-compose.yml

```yaml
services:
  docusaurus:
    image: node:20-alpine
    working_dir: /app
    command: sh -c "npm install && npm run start -- --host 0.0.0.0"
    ports:
      - "3000:3000"
    volumes:
      - ./docs:/app
      - node_modules:/app/node_modules
    environment:
      - NODE_ENV=development
    networks:
      - docs_net

  docusaurus-build:
    image: node:20-alpine
    working_dir: /app
    command: sh -c "npm install && npm run build"
    volumes:
      - ./docs:/app
      - node_modules:/app/node_modules
      - ./build:/app/build
    profiles:
      - build
    networks:
      - docs_net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./build:/usr/share/nginx/html:ro
    profiles:
      - production
    networks:
      - docs_net

volumes:
  node_modules:

networks:
  docs_net:
```

## .env

```bash
# Docusaurus
# Dev server at http://localhost:3000
# Build with: docker compose --profile build up
# Production with: docker compose --profile production up
```

## Usage notes

- Dev server at http://localhost:3000
- Hot reload for development
- Build with --profile build
- Serve built site with nginx
- MDX for React in Markdown

## Troubleshooting

- Module not found errors during npm install: Ensure ./docs directory contains valid package.json with @docusaurus/core dependencies
- Hot-reload not working in development: Check that files are mounted correctly and NODE_ENV=development is set in container
- NGINX 403 Forbidden on production: Verify build directory is properly mounted and contains generated static files from npm run build
- Docusaurus build fails with memory errors: Increase Docker container memory limits or use --max-old-space-size Node.js flag
- Search not working: Confirm Algolia DocSearch crawler has indexed the site and API keys are configured in docusaurus.config.js
- Port 3000 already in use: Stop other Node.js processes or modify the port mapping in docker-compose.yml

