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-focused 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:

  • MPA vs SPA: 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 an official docs theme. This website was the inspiration for that template! 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 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

Add our MDX integration and bring your existing content files to create MDX pages. You can still take advantage of file-based routing by copying these documents directly into src/pages/ in Astro, the same folder you currently use. Create folders with names that correspond to your existing Docusaurus project, and you should be able to keep your existing URLs.

Docusaurus probably handled much of your site layout and metadata for you. You may wish to read about building Astro Layouts as page wrappers for Markdown and MDX to see how to manage templating yourself in Astro, including your page <head>.

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.

Community Resources

Section titled Community Resources
  • Add your own!

More migration guides