Skip to content

Migrating from Docusaurus

Docusaurus is a popular documentation website builder built on React.

Key Similarities between Docusaurus and Astro

Section titled Key Similarities between Docusaurus and Astro

Docusaurus and Astro share some similarities that will help you migrate your project:

  • Both Astro and Docusaurus are modern, JavaScript-based (Jamstack) site builders intended for content-driven websites, like documentation sites.

  • Both Astro and Docusaurus support MDX pages. You should be able to use your existing .mdx files to Astro.

  • Both Astro and Docusaurus use file-based routing to generate page routes automatically for any MDX file located in src/pages. Using Astro’s file structure for your existing content and when adding new pages should feel familiar.

  • Astro has an official integration for using React components. Note that in Astro, React files must have a .jsx or .tsx extension.

  • Astro supports installing NPM packages, including several for React. You may be able to keep some or all of your existing React components and dependencies.

  • Astro’s JSX-like syntax should feel familiar if you are used to writing React.

Key Differences between Docusaurus and Astro

Section titled Key Differences between Docusaurus and Astro

When you rebuild your Docusaurus site in Astro, you will notice some important differences:

  • Docusaurus is a React-based single-page application (SPA). Astro sites are multi-page apps built using .astro components, but can also support React, Preact, Vue.js, Svelte, SolidJS, AlpineJS, Lit and raw HTML templating.

  • Docusaurus was designed to build documentation websites and has some built-in, documentation-specific website features that you would have to build yourself in Astro. Instead, Astro offers some of these features through Starlight: an official docs theme. This website was the inspiration for Starlight, and now runs on it! You can also find more community docs themes with built-in features in our Themes Showcase.

  • Docusaurus sites use MDX pages for content. Astro’s docs theme uses Markdown (.md) files by default and does not require you to use MDX. You can optionally install Astro’s MDX integration (included in our Starlight theme by default) and use .mdx files in addition to standard Markdown files.

Switch from Docusaurus to Astro

Section titled Switch from Docusaurus to Astro

To convert a Docusaurus documentation site to Astro, start with our official Starlight docs theme starter template, or explore more community docs themes in our theme showcase.

You can pass a --template argument to the create astro command to start a new Astro project with one of our official starters. Or, you can start a new project from any existing Astro repository on GitHub.

Terminal window
npm create astro@latest -- --template starlight

Astro’s MDX integration is included by default, so you can bring your existing content files to Starlight right away.

You can find Astro’s docs starter, and other official templates, on astro.new. You’ll find a link to each project’s GitHub repository, as well as one-click links to open a working project in StackBlitz, CodeSandbox and Gitpod online development environments.

  • Add your own!

More migration guides