docusaurus build: Compile a Docusaurus Site
docusaurus build compiles a Docusaurus project into static HTML/JS under build/, and by default it fails the build on broken internal links.
Docusaurus is a React-based docs framework. docusaurus build (usually via npm run build) is the CI command; its onBrokenLinks default of throw already gives you a link gate for free.
What it does
docusaurus build runs the production build: it renders every route to static HTML, bundles the client JS, and writes to build/. With the default onBrokenLinks: 'throw' it aborts if any internal link points at a nonexistent page.
Common usage
npm run build # runs "docusaurus build"
# or directly
npx docusaurus build --out-dir dist
# build a specific locale
npx docusaurus build --locale frOptions
| Flag / config | What it does |
|---|---|
| --out-dir <dir> | Output directory (default build) |
| --locale <name> | Build only one locale |
| --no-minify | Skip minification (faster debug builds) |
| onBrokenLinks | Config: throw | warn | ignore for broken links |
| onBrokenMarkdownLinks | Config: how to treat broken markdown links |
In CI
Keep onBrokenLinks: 'throw' so dead links fail the pipeline. Set NODE_OPTIONS=--max-old-space-size=4096 for large sites that hit the heap limit. Cache node_modules and the .docusaurus folder; the output goes to build/ for deployment.
Common errors in CI
Error: Docusaurus found broken links! ... Please check the pages ... is the default link-check failure; fix the link or relax onBrokenLinks. FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory needs a larger --max-old-space-size. MDX compilation failed points at invalid JSX/MDX in a doc page.