Onboarding: facebook/docusaurus

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 3d ago
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 57% of commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Docusaurus is a Facebook/Meta-maintained static site generator purpose-built for open source documentation websites. It combines React-based theming, MDX (Markdown + JSX) content authoring, versioned docs, i18n, and plugin-driven extensibility into a single CLI tool (@docusaurus/core). The specific problem it solves is letting engineering teams ship searchable, versioned, internationalized documentation sites without building custom tooling from scratch. This is a Yarn/npm monorepo where core packages live under packages/ (not shown in top-60 but referenced throughout): @docusaurus/core is the build engine, @docusaurus/preset-classic bundles the default theme and plugins, and packages/docusaurus-theme-classic contains the React UI components. The website/ directory is the self-hosting Docusaurus docs site, and examples/ holds scaffolding templates. The root .eslintrc.js, .prettierrc, and .syncpackrc.ts enforce monorepo-wide code standards.

Who it's for

Open source maintainers and developer-relations engineers at companies like Meta, Vercel, and Stripe who need to publish and version technical documentation. Contributors are typically TypeScript/React developers who extend the plugin system or improve the CLI/theme packages within the monorepo.

Maturity & risk

Docusaurus is production-ready and battle-tested: it powers hundreds of major OSS project docs sites (React, Jest, Redux, etc.), is on v3.x, and has a comprehensive CI setup across .github/workflows/ including lint, e2e tests (tests-e2e.yml), Windows tests (tests-windows.yml), Lighthouse audits (lighthouse-report.yml), and visual regression via Argos (argos.yml). The CHANGELOG.md and CHANGELOG-v2.md show continuous active development with regular releases via continuous-releases.yml.

Low risk for consumers: Meta backs it, there is a CODEOWNERS file indicating distributed ownership, and the dependabot.yml keeps dependencies updated. The main risk is the large TypeScript surface area (3M+ bytes) and a plugin/swizzling API that has historically had breaking changes between major versions (v2→v3), as evidenced by the separate CHANGELOG-v2.md and the tests-swizzle.yml CI job dedicated to catching swizzle regressions.

Active areas of work

Based on the workflows present, active work includes: continuous releases via continuous-releases.yml (canary/nightly builds), performance benchmarking via build-perf.yml, hash-router support (build-hash-router.yml), and supply chain security hardening (security-supply-chain.yml, dependency-review.yml). The AGENTS.md file (a recent addition) suggests AI agent/automation integration is being explored.

Get running

git clone https://github.com/facebook/docusaurus.git && cd docusaurus && node --version # must match .nvmrc (check version) && yarn install && yarn build && cd website && yarn start

Daily commands:

Run the Docusaurus documentation website locally:

cd website && yarn start

Run all tests from repo root:

yarn test

Build all packages:

yarn build

For the docusaurus.new redirect function (new.docusaurus.io):

npx --package netlify-cli netlify dev

Map of the codebase

• .eslintrc.js — Root ESLint configuration that enforces coding standards across all packages in this monorepo — every contributor must follow these rules to pass CI.
• admin/new.docusaurus.io/functions/index.ts — Entry point for the Netlify serverless functions that power new.docusaurus.io, routing requests to CodeSandbox and StackBlitz playground generators.
• admin/new.docusaurus.io/functionUtils/playgroundUtils.ts — Core utility shared by all playground generator functions, containing the logic for constructing sandbox/playground payloads from Docusaurus templates.
• admin/new.docusaurus.io/functions/codesandbox.ts — Netlify function that generates CodeSandbox playground links for Docusaurus — understanding this is required to add or modify JS template playground support.
• admin/new.docusaurus.io/functions/stackblitz.ts — Netlify function that generates StackBlitz playground links — mirrors the codesandbox.ts pattern and must stay in sync for feature parity.
• __tests__/validate-package-json.test.ts — Validates that all package.json files in the monorepo conform to required structure — a load-bearing test that enforces monorepo package hygiene.
• .github/workflows/tests.yml — Primary CI workflow that runs the full test suite — defines the gates every PR must pass, making it essential reading for contributors.

How to make changes

Add a new playground provider (e.g. Gitpod)

1. Create a new Netlify function file following the naming convention of existing providers, implementing the handler that builds the provider-specific URL (admin/new.docusaurus.io/functions/gitpod.ts)
2. Add shared URL-building or payload-construction helpers to the central utility module, reusing existing patterns (admin/new.docusaurus.io/functionUtils/playgroundUtils.ts)
3. Register the new function route in the main index entry point so it is dispatched correctly by Netlify (admin/new.docusaurus.io/functions/index.ts)
4. Update the Netlify config to add any required redirect or function binding for the new route (admin/new.docusaurus.io/netlify.toml)

Add a new Docusaurus example template

1. Create a new directory under examples/ following the existing classic-typescript structure with blog, docs, and src folders (examples/classic-typescript)
2. Add representative MDX blog posts and docs pages that showcase Docusaurus features for the new template variant (examples/classic-typescript/blog/2021-08-01-mdx-blog-post.mdx)
3. Update the example generation script to include the new template directory in its generation pass (admin/scripts/generateExamples.js)

Add a new CI workflow (e.g. bundle size check)

1. Create a new YAML workflow file in the workflows directory, referencing the existing tests.yml as a structural template (.github/workflows/tests.yml)
2. If the workflow needs to post PR comments or upload artifacts, reference the Lighthouse report formatter script as a pattern (admin/scripts/formatLighthouseReport.js)

Add visual regression screenshots for a new page

1. Add a new Playwright test case in the Argos screenshot spec that navigates to the new page URL and triggers a screenshot (argos/tests/screenshot.spec.ts)
2. Add any necessary CSS overrides to stabilize animations or dynamic content for screenshot consistency (argos/tests/screenshot.css)
3. Verify the Argos workflow will pick up the new screenshots by reviewing the workflow trigger configuration (.github/workflows/argos.yml)

Why these technologies

• Netlify Functions (@netlify/functions) — Provides zero-infrastructure serverless execution for playground redirect logic without needing a dedicated server, matching the static-site-first philosophy of Docusaurus.
• TypeScript — Used throughout the functions and utilities to catch type errors at build time and provide better IDE support across a large contributor base.
• GitHub Actions — Native CI/CD integration with the GitHub-hosted repository, enabling matrix builds, caching, and tight PR status integration without third-party CI services.
• Playwright + Argos — Playwright handles cross-browser E2E testing while Argos provides visual regression diffing on screenshots, catching UI regressions that unit tests cannot.
• ESLint + Prettier + Stylelint — Three-layer linting strategy ensures consistent code style (Prettier), correct logic (ESLint), and valid CSS (Stylelint) enforced uniformly across the monorepo.

Trade-offs already made

• Separate serverless functions per playground provider (codesandbox.ts, stackblitz.ts, etc.)

  • Why: Each provider has different API contracts and payload shapes, so isolating them prevents tight coupling and makes each independently testable.
  • Consequence: Adding a new provider requires creating a new file and registering it, but there is minimal shared abstraction to break accidentally.

• URL-based StackBlitz integration vs API-based CodeSandbox integration

  • Why: StackBlitz supports project definition via encoded URL parameters, avoiding an extra HTTP round-trip and making it faster and more reliable.
  • Consequence: StackBlitz payloads are size-constrained by URL length limits, while CodeSandbox supports larger projects at the cost of latency.

• Monorepo structure with syncpack for dependency management

  • Why: Keeps all Docusaurus packages versioned together and prevents dependency drift across packages, critical for a framework where packages must interoperate.
  • Consequence: Updating a shared dependency requires coordinating across all packages and re-running syncpack checks, adding overhead to dependency upgrades.

Non-goals (don't propose these)

• Does not host or serve documentation content itself — it generates static sites that users deploy independently
• Does not provide a backend CMS or database for documentation content
• Does not handle authentication or access control for documentation sites
• Does not support server-side rendering at runtime — output is always static HTML (SSG only, no SSR server

Traps & gotchas

1. The .nvmrc pins a specific Node.js version — mismatches cause cryptic build failures; always use nvm use first. 2) Swizzling (ejecting theme components) is version-sensitive; the tests-swizzle.yml workflow exists specifically because this API breaks easily. 3) The new.docusaurus.io subdirectory has its own package.json with @netlify/functions and requires the Netlify CLI to run locally, not the standard yarn start. 4) .gitattributes likely enforces LF line endings (common cross-platform issue on Windows contributors). 5) The .syncpackrc.ts enforces dependency version consistency across workspace packages — adding a dep without syncing will fail CI.

Architecture

Concepts to learn

• MDX (Markdown + JSX) — All Docusaurus content is authored in MDX; understanding how remark/rehype plugins transform .mdx files is essential for debugging content rendering and writing custom plugins.
• Swizzling (component ejection) — Docusaurus's unique mechanism for overriding theme components by copying them into the user's project — it has a safe/unsafe API surface and is the source of many upgrade-breaking changes.
• Static Site Generation (SSG) with React hydration — Docusaurus pre-renders all pages to static HTML at build time then hydrates them client-side with React — understanding the SSG/hydration boundary is critical for debugging layout shifts and missing interactivity.
• Yarn Workspaces (monorepo) — All packages share a single node_modules hoisted at the repo root via Yarn workspaces; .syncpackrc.ts enforces version consistency, and understanding hoisting is required to diagnose phantom dependency issues.
• Remark/Rehype plugin pipeline — Docusaurus processes Markdown through a remark (Markdown AST) then rehype (HTML AST) pipeline; custom content transformations and syntax extensions are written as plugins in this pipeline.
• Infima CSS design system — Docusaurus classic theme is built on Infima, a CSS framework with CSS custom properties for theming — understanding Infima's variable naming conventions is required for any visual/styling contributions.
• Hash router (client-side routing fallback) — The build-hash-router.yml CI workflow builds a hash-router variant of the site, an alternative routing mode for environments that cannot configure server-side redirects — non-obvious deployment edge case.

Related repos

• withastro/astro — Direct alternative static site/docs generator in the same JS ecosystem with MDX support and growing docs-site use cases.
• vuejs/vitepress — Close alternative documentation site generator built on Vite/Vue, frequently compared to Docusaurus for OSS docs.
• facebook/jest — Major OSS project whose documentation site is built with Docusaurus, making it a canonical real-world consumer of this repo.
• slorber/docusaurus-starter — The starter template referenced in the Netlify deploy button in the README — companion repo for bootstrapping new Docusaurus sites.
• mdx-js/mdx — Core dependency powering the MDX content pipeline that Docusaurus relies on for mixing Markdown with React components.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for admin/new.docusaurus.io playground utility functions

The admin/new.docusaurus.io/functionUtils/playgroundUtils.ts and the four Netlify functions (codesandbox.ts, codesandbox-ts.ts, stackblitz.ts, stackblitz-ts.ts) have no corresponding test files. These functions power the public playground redirector at new.docusaurus.io, which is critical for new user onboarding. Unit tests would catch regressions in URL generation, payload construction, and template parameter handling without needing a live Netlify environment.

• [ ] Create admin/new.docusaurus.io/__tests__/playgroundUtils.test.ts and write unit tests for all exported helpers in functionUtils/playgroundUtils.ts, covering edge cases like missing parameters and special characters in project names
• [ ] Create admin/new.docusaurus.io/__tests__/codesandbox.test.ts and codesandbox-ts.test.ts mocking @netlify/functions handler inputs and asserting correct redirect URLs and status codes are returned
• [ ] Create admin/new.docusaurus.io/__tests__/stackblitz.test.ts and stackblitz-ts.test.ts with equivalent handler tests, ensuring TypeScript vs JavaScript template branching is covered
• [ ] Add a test script to admin/new.docusaurus.io/package.json (currently missing) that runs the new test suite with Jest or Vitest
• [ ] Update CONTRIBUTING.md or a local README inside admin/new.docusaurus.io/ to document how to run these tests

Add a GitHub Actions workflow to validate Netlify function builds in admin/new.docusaurus.io

The .github/workflows/ directory contains many CI workflows (tests, lint, e2e, swizzle, windows, etc.) but none specifically build or type-check the admin/new.docusaurus.io Netlify functions. Since these TypeScript functions are deployed independently via Netlify CLI, a broken build would only be caught at deploy time. A dedicated workflow would catch TypeScript compilation errors and missing dependency issues on every PR that touches the admin/ directory.

• [ ] Create .github/workflows/build-new-docusaurus-io.yml with a job that runs only when files under admin/new.docusaurus.io/** change, using paths filtering
• [ ] In the workflow, install dependencies with npm ci inside admin/new.docusaurus.io/ and run tsc --noEmit to type-check all functions and utilities without emitting output
• [ ] Add a step that runs npx netlify-cli build (or equivalent dry-run) to validate the Netlify function bundling succeeds
• [ ] Pin the Node.js version in the workflow to match the .nvmrc at the repo root for consistency
• [ ] Reference this new workflow in .github/CODEOWNERS so the appropriate team is notified on changes to the admin subdirectory

Split validate-package-json.test.ts and validate-tsconfig.test.ts into focused, per-concern test modules

The root-level __tests__/validate-package-json.test.ts and __tests__/validate-tsconfig.test.ts are monolithic validation files that likely assert many different rules (version consistency, field presence, tsconfig path correctness, etc.) in a single file each. As the monorepo grows, these become hard to maintain and slow to debug when one rule fails. Splitting them into focused modules improves discoverability and makes it easier for contributors to add new validations without touching a large shared file.

• [ ] Audit __tests__/validate-package-json.test.ts and identify distinct concern groups (e.g., required fields, version consistency via .syncpackrc.ts, private flag rules, scripts validation) and extract each into `tests/package

Good first issues

1. Add missing unit tests for specific CLI commands in packages/docusaurus/src/commands/ — the test coverage for individual command modules is likely incomplete given the complexity. 2) Improve cspell dictionary (.cspell.json) by auditing false-positive words flagged in non-English i18n content files in website/i18n/. 3) Add Lighthouse CI budget assertions in .github/workflows/lighthouserc.json for specific metric thresholds (currently the config may lack per-route budgets for blog-only builds tested in build-blog-only.yml).

Top contributors

• @slorber — 49 commits
• @dependabot[bot] — 32 commits
• @dmoranp — 2 commits
• @akshatsinha0 — 2 commits
• @LiuHuaize — 1 commits

Recent commits

• 3f10bdc — chore: bump package.json versions, mostly for canary release versioning (#11980) (slorber)
• f3e8105 — chore: update examples for v3.10.1 (#11985) (slorber)
• 238c71e — chore: release v3.10.1 (#11983) (slorber)
• 11b594d — fix(i18n): regression bug: i18n/<path> should always use locale key/id, not htmlLang (#11979) (slorber)
• 52eb721 — fix(website): Replace changelog emoji for performance PRs (#11978) (slorber)
• 49e10d2 — chore: update various dependencies (#11975) (slorber)
• 8c05ce7 — docs: add package-manager tabs for create-docusaurus (#11925) (LiuHuaize)
• aedb78e — docs: Update example file from tags.yml to authors.yml (#11973) (KevinWinardi)
• 0942489 — chore(deps): bump follow-redirects from 1.15.11 to 1.16.0 (#11942) (dependabot[bot])
• 9872a42 — chore(deps): bump postcss from 8.5.9 to 8.5.10 (#11968) (dependabot[bot])

Security observations

• Medium · Outdated @netlify/functions Dependency with Broad Version Range — admin/new.docusaurus.io/package.json. The package.json for new.docusaurus.io specifies '@netlify/functions': '^1.6.0', which allows automatic minor and patch upgrades. Version 1.x of @netlify/functions is a legacy major version, and using a broad caret range means the project could inadvertently pull in versions with unpatched vulnerabilities without explicit review. The current latest in the 1.x line may also lag behind security fixes present in the 2.x branch. Fix: Pin the dependency to a specific, audited version (e.g., '1.6.0') and regularly run 'npm audit' or use Dependabot (already configured at .github/dependabot.yml) to receive alerts. Consider migrating to @netlify/functions v2.x if compatible.
• Medium · Use of npx with Unpinned netlify-cli in Start Script — admin/new.docusaurus.io/package.json (scripts.start). The 'start' script runs 'npx --package netlify-cli netlify dev', which downloads and executes the latest available version of netlify-cli at runtime without pinning a specific version. This introduces a supply-chain risk: a compromised or malicious release of netlify-cli on npm could be automatically fetched and executed in the development environment. Fix: Pin netlify-cli to a specific version by adding it as a devDependency (e.g., 'netlify-cli': '17.x.x') and update the start script to simply call 'netlify dev'. Regularly audit and update this pinned version.
• Medium · Potential XSS via dangerouslySetInnerHTML in Documentation Website — General codebase / MDX rendering pipeline. Docusaurus-based projects commonly use React's 'dangerouslySetInnerHTML' for rendering raw HTML content from Markdown, MDX, or plugin-generated content. If user-supplied or externally sourced content is rendered without proper sanitization, it could result in stored or reflected XSS attacks. Given the file structure includes MDX files (e.g., admin/test-bad-package/README.mdx) and a plugin-rich architecture, this risk surface exists. Fix: Audit all usages of 'dangerouslySetInnerHTML' in the codebase. Ensure all user-supplied or externally fetched content is sanitized with a library such as DOMPurify before rendering. Enable a strict Content Security Policy (CSP) header to mitigate XSS impact.
• Medium · Missing Security Headers Configuration — admin/new.docusaurus.io/netlify.toml. The netlify.toml for new.docusaurus.io is listed in the file structure but its content is not provided. Netlify deployments without explicit security header configuration (e.g., Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy) are susceptible to clickjacking, MIME sniffing, and other browser-based attacks. Fix: Add a [[headers]] section to netlify.toml defining at minimum: 'X-Frame-Options: DENY', 'X-Content-Type-Options: nosniff', 'Referrer-Policy: strict-origin-when-cross-origin', 'Permissions-Policy: geolocation=(), camera=(), microphone=()', and a strict 'Content-Security-Policy' header.
• Low · Serverless Function Code Handles External Input Without Visible Validation — admin/new.docusaurus.io/functions/, admin/new.docusaurus.io/functionUtils/playgroundUtils.ts. The serverless functions under admin/new.docusaurus.io/functions/ (codesandbox.ts, codesandbox-ts.ts, stackblitz.ts, stackblitz-ts.ts, index.ts) and utility code in functionUtils/playgroundUtils.ts appear to construct payloads for third-party sandbox services (CodeSandbox, StackBlitz). Without seeing the full source, there is a risk that external user input passed to these functions is not validated or sanitized before being forwarded, potentially enabling injection or SSRF-like abuse. Fix: Audit all Netlify function handlers to ensure: (1) all incoming request parameters are validated and sanitized, (2) only expected fields are forwarded to third-party APIs

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.