# facebook/docusaurus architecture

> Architecture diagram of the GitHub repository facebook/docusaurus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/docusaurus
- Repository: https://github.com/facebook/docusaurus

## Overview

##### Project type and purpose
- This is a monorepo for Docusaurus, a static‐site generator and framework for building documentation and blog websites.
- It provides a CLI (`packages/docusaurus/bin`), a core orchestrator (`@docusaurus/core`), a plugin system (dozens of `packages/docusaurus-plugin-*`), themes (`packages/docusaurus-theme-*`), loaders (e.g. MDX loader), a bundler module (`@docusaurus-bundler`), and an SSG executor.

##### File structure
- Top level:
- `packages/` – all core packages (core engine, plugins, themes, babel preset, bundler, etc.)
- `examples/` – sample sites
- `website/` – the Docusaurus website built with the framework itself
- Build tools & config files (`lerna.json`, `jest.config.mjs`, `.github/workflows`, etc.)
- Patterns:
- Monorepo (Lerna) with independent packages that plugin into the core
- Plugin architecture: each plugin exposes lifecycle hooks that the core invokes
- Loader pipeline: MDX → Remark transforms → Babel → Webpack loaders → Bundler

##### README for additional insights
- Highlights: CLI for creating a site, customizable plugin/theme system, i18n built-in, uses React under the hood, outputs static HTML + client bundles.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    Dev(["Developer"]):::external

    %% CLI
    CLI["CLI"]:::core
    Dev -->|"runs"| CLI
    click CLI "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/bin/docusaurus.mjs"
    click CLI "https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/bin/index.js"
    click CLI "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/commands/cli.ts"

    %% Config Loader
    Config["Config Loader"]:::core
    CLI -->|"load config"| Config
    click Config "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/config.ts"
    click Config "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/configValidation.ts"

    %% Core Orchestrator
    Core["Core Orchestrator (@docusaurus/core)"]:::core
    Config -->|"bootstrap"| Core
    click Core "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/index.ts"
    click Core "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/client/ClientLifecyclesDispatcher.tsx"
    click Core "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/site.ts"

    %% Plugin System
    PluginLoader["Plugin Loader"]:::plugin
    Core -->|"init plugins"| PluginLoader
    click PluginLoader "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/plugins/init.ts"
    click PluginLoader "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/server/plugins/plugins.ts"

    subgraph "Plugin System"
      ContentPL["Content Plugins"]:::plugin
      UtilityPL["Utility Plugins"]:::plugin
    end
    PluginLoader --> ContentPL
    PluginLoader --> UtilityPL
    ContentPL -->|"provide content hooks"| Core
    UtilityPL -->|"modify pipeline"| Core

    %% Loader Pipeline
    Core -->|"process files"| Loader["Loader Pipeline"]:::pipeline
    subgraph "Loader Pipeline"
      MDX["MDX Loader"]:::pipeline
      Remark["Remark Transforms"]:::pipeline
      BabelExtract["Babel Extractor"]:::pipeline
    end
    click MDX "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/index.ts"
    click Remark "https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-mdx-loader/src/remark/"
    click BabelExtract "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-babel/src/babelTranslationsExtractor.ts"
    Loader -->|"transformed JS/React"| Bundler

    %% Bundler
    Bundler["Bundler (@docusaurus-bundler)"]:::pipeline
    click Bundler "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/index.ts"
    click Bundler "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/compiler.ts"
    click Bundler "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/loaders/jsLoader.ts"
    click Bundler "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-bundler/src/loaders/styleLoader.ts"

    %% Theme Layer
    subgraph "Theme Layer"
      ThemeCore["Classic Theme & Components"]:::plugin
      OtherThemes["Other Themes"]:::plugin
    end
    click ThemeCore "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/index.ts"
    click ThemeCore "https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/"
    Core -->|"inject theme runtime"| ThemeCore
    Bundler -->|"inject CSS/JS"| ThemeCore

    Bundler -->|"bundle assets"| SSG

    %% SSG Executor
    SSG["SSG Executor"]:::pipeline
    click SSG "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/ssg/ssgExecutor.ts"
    click SSG "https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/ssg/ssgRenderer.ts"
    SSG -->|"render static HTML"| Output

    %% Output & Deployment
    Output["Output (HTML, JS, CSS, Assets)"]:::core
    Output -->|"deploy"| GH["GitHub Pages"]:::external
    Output -->|"deploy"| Netlify["Netlify"]:::external
    Output -->|"deploy"| Vercel["Vercel"]:::external
    click Netlify "https://github.com/facebook/docusaurus/blob/main/website/netlify.toml"
    click GH "https://github.com/facebook/docusaurus/blob/main/.github/workflows/continuous-releases.yml"

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#bfb,stroke:#333,stroke-width:1px
    classDef pipeline fill:#fab,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
