I was evaluating Docusaurus as a replacement for our Redocly docs site. We had around 200 documentation pages and needed more flexibility than Redocly could offer. Turns out Docusaurus was exactly what we needed.

Why Docusaurus over other doc tools Link to heading

I looked at a few options:

  • Redocly - Excellent for pure OpenAPI reference docs, but limited customisation and no good way to add interactive examples
  • GitBook - Nice UI but expensive for teams, and you’re locked into their platform
  • VitePress - Very fast but Vue-focused, and we already had React components we wanted to reuse
  • Nextra - Good Next.js integration, but Docusaurus has better versioning and plugin ecosystem
  • MkDocs - Python-based, which would have meant learning Jinja templates

Docusaurus won because:

  • Built on React, so we could drop in our existing component library
  • Versioning is first-class (vital for API docs with multiple versions)
  • MDX support means you can embed any React component in markdown
  • Algolia DocSearch integration is free and trivial to set up
  • Large community and active development

Why migrate from Redocly Link to heading

Redocly is good for pure API reference docs, but we needed:

  • Custom React components for interactive examples (like an API playground)
  • Full-text search across all docs (not just API specs)
  • MDX support for embedding components in markdown
  • Better versioning for multiple API versions
  • Tutorials and guides alongside the API reference

Docusaurus handles all of this out of the box.

Quick start Link to heading

npx create-docusaurus@latest my-docs classic
cd my-docs
npm start

The migration Link to heading

Most markdown files copy over directly. The main differences:

Front matter - Redocly uses label, Docusaurus uses sidebar_label:

---
sidebar_position: 1
sidebar_label: "Getting Started"
---

URL parameters - Use query strings, not colon syntax:

# Redocly style (doesn't work)
[Link](/docs/page/:param)

# Docusaurus style (works)
[Link](/docs/page?param=value)

OpenAPI integration Link to heading

For API reference docs, use the docusaurus-plugin-openapi-docs plugin. It generates MDX pages from your OpenAPI spec.

Customisations we made Link to heading

  1. Custom API playground component - Built an interactive request builder using React that reads from our OpenAPI spec
  2. Code snippet tabs - Created a component to show examples in multiple languages (Python, JavaScript, cURL)
  3. Custom theme colours - Matched our brand colours in docusaurus.config.js
  4. Search context - Added custom search metadata to improve Algolia results

The best part is that all of these are just React components in a src/components directory. No fighting with template languages or build systems.

What I liked Link to heading

  • Versioned docs built in - just run npm run docusaurus docs:version 2.0 to snapshot your docs
  • Algolia search integration is trivial - add your API keys and it works
  • React components can be used anywhere - import and use them in any MDX file
  • Fast hot reload during development - changes appear instantly

The React ecosystem means you can build whatever custom components you need, which was the main limitation with Redocly. If you can build it in React, you can put it in your docs.

Further reading Link to heading