Docusaurus Documentation Site

beginner

Modern documentation site with Docusaurus, search, and versioning.

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.

Key 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

Common Use Cases

1Open-source project documentation with community contributions via Git workflows
2API documentation sites combining generated references with hand-written guides
3Internal company knowledge bases requiring search and version control
4Product documentation for SaaS platforms with user-facing help centers
5Technical blog platforms combining articles with structured documentation
6Educational content platforms teaching programming concepts with interactive examples
7Software 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  docusaurus: 
3    image: node:20-alpine
4    working_dir: /app
5    command: sh -c "npm install && npm run start -- --host 0.0.0.0"
6    ports: 
7      - "3000:3000"
8    volumes: 
9      - ./docs:/app
10      - node_modules:/app/node_modules
11    environment: 
12      - NODE_ENV=development
13    networks: 
14      - docs_net
15
16  docusaurus-build: 
17    image: node:20-alpine
18    working_dir: /app
19    command: sh -c "npm install && npm run build"
20    volumes: 
21      - ./docs:/app
22      - node_modules:/app/node_modules
23      - ./build:/app/build
24    profiles: 
25      - build
26    networks: 
27      - docs_net
28
29  nginx: 
30    image: nginx:alpine
31    ports: 
32      - "80:80"
33    volumes: 
34      - ./build:/usr/share/nginx/html:ro
35    profiles: 
36      - production
37    networks: 
38      - docs_net
39
40volumes: 
41  node_modules: 
42
43networks: 
44  docs_net:

.env Template

.env

1# Docusaurus
2# Dev server at http://localhost:3000
3# Build with: docker compose --profile build up
4# Production with: docker compose --profile production up

Usage Notes

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

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

docusaurus

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  docusaurus:
5    image: node:20-alpine
6    working_dir: /app
7    command: sh -c "npm install && npm run start -- --host 0.0.0.0"
8    ports:
9      - "3000:3000"
10    volumes:
11      - ./docs:/app
12      - node_modules:/app/node_modules
13    environment:
14      - NODE_ENV=development
15    networks:
16      - docs_net
17
18  docusaurus-build:
19    image: node:20-alpine
20    working_dir: /app
21    command: sh -c "npm install && npm run build"
22    volumes:
23      - ./docs:/app
24      - node_modules:/app/node_modules
25      - ./build:/app/build
26    profiles:
27      - build
28    networks:
29      - docs_net
30
31  nginx:
32    image: nginx:alpine
33    ports:
34      - "80:80"
35    volumes:
36      - ./build:/usr/share/nginx/html:ro
37    profiles:
38      - production
39    networks:
40      - docs_net
41
42volumes:
43  node_modules:
44
45networks:
46  docs_net:
47EOF
48
49# 2. Create the .env file
50cat > .env << 'EOF'
51# Docusaurus
52# Dev server at http://localhost:3000
53# Build with: docker compose --profile build up
54# Production with: docker compose --profile production up
55EOF
56
57# 3. Start the services
58docker compose up -d
59
60# 4. View logs
61docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/docusaurus-docs/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

docusaurusalgolia-docsearchnginx

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download