Starlight vs. Docusaurus for building documentation
Tags: astro, docusaurus, webdev
Published: 2024-02-13 15:23:16

**Written by [Kapeel Kokane
](https://blog.logrocket.com/author/kapeelkokane/)✏️**

Modern frontend development frameworks have advanced tremendously in the past few years, making it easier to build full-fledged web apps with dynamic functionality. But, that might not be something that we always need. For example, if we want to build a static, information-heavy site (like a documentation website), a framework might not be the best choice because the main focus is the content and not the infrastructure maintenance. 

In that case, what we need would be closer to a static site generator (like [Gatsby](https://www.gatsbyjs.com/), [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/)). But, static site generators aren't the best choice either because we would have to build a lot of documentation-focused functionality (like versioning, search, and code blocks) ourselves. 

This is where Docusaurus and Starlight come in. Both of them are designed from the ground up for documentation websites. Docusaurus is the more mature among the two, while Starlight is still under beta. In this article, we will explore how both of these tools compare with each other on several factors, including their ease of deployment, support for features like light/dark mode and sidebars, and more.

## Introduction to Docusaurus

Created by Facebook, [Docusaurus](https://docusaurus.io/) is an open source static site generator built on top of React. Docusaurus is also used by several platforms like Redux, Ionic, Supabase, etc. to host their documentation. They recently released version 3.0 of the framework. The generator provides documentation-centric features like MDX support, versioning, translation, search, and loads of customization options.

## Introduction to Starlight

[Starlight](https://starlight.astro.build/) is a static site generator built on top of [Astro](https://astro.build/). It is also open source but not as feature-rich as Docusaurus because it is still in beta. Regardless, it still provides features like MXD support, navigation, search, code blocks, etc. One advantage of being built on top of Astro is that custom components can be written in our favorite frameworks like Svelte, Vue, and Solid in addition to React.

## Getting started

Both Docusaurus and Starlight provide CLI options to help us get started. All we need is Node and npm installed on our system.

### Creating a new Docusaurus project

To create a new Docusaurus project, we can use the following command:

```bash
npx create-docusaurus@latest docusaurus-site classic
```

This creates a new project with the name `my-website`. By passing the `classic` flag, we are utilizing `@docusaurus/preset-classic`. This preset is a collection of several core features like documentation, blog, custom pages, and CSS support. Additionally, we can pass the `--typescript` flag to enable TypeScript support:

```bash
npx create-docusaurus@latest docusaurus-site classic --typescript
```

Once the script has finished running, we can navigate to the project folder and start the local dev server:

```bash
cd docusaurus-site
npm run start
```

That brings up the local dev server at `http://localhost:3000`. It looks something like this: ![Setting Up A New Docusaurus Project](https://blog.logrocket.com/wp-content/uploads/2024/01/setting-up-new-docusaurus-project.gif) As you can see, we already have quite a lot of functionality out of the box. We will come back to this later in the article.

### Creating a new Starlight project

Getting started with Starlight is equally easy. We need to use this command:

```bash
npm create astro@latest -- --template starlight
```

This opens an elaborate CLI wizard that guides us through the process. At the end of it, we have a new directory with a fresh Astro project, with or without TypeScript support. We can `ls` into the project directory and start the local dev server:

```bash
ls starlight-site
npm run dev
```

The following site will come up on localhost: ![New Starlight Project](https://blog.logrocket.com/wp-content/uploads/2024/01/New-Starlight-Project_e1bb18.gif) Although not as exhaustive as Docusaurus, Starlight still has some functionality out of the box. We will explore this in detail later in the article.

## Ease of deployment

Both Docusaurus and Starlight generate static sites. This means that theoretically, they can be deployed on any platform that supports deploying static sites (like [Apache](https://httpd.apache.org/) or [NGINX](https://www.nginx.com/)). But both of them provide a significantly better developer experience if we deploy on their recommended platforms.

### Docusaurus deployment

Docusaurus supports simple deployment on platforms like [Vercel](https://vercel.com/) and [Netlify](https://www.netlify.com/), Vercel being the recommended option. For deploying on Vercel, we just need to import the GitHub repository of our Docusaurus site to Vercel and it will take care of the rest. We can deploy with the default options selected: ![Deploying Our Docusaurus Site To Vercel](https://blog.logrocket.com/wp-content/uploads/2024/01/deploying-docusaurus-site-vercel.png) An additional benefit of deploying this way is that we get the latest production deployment to run whenever we push to the main branch of the imported GitHub repository.

### Starlight deployment

Deploying a Starlight project is as good as deploying any Astro site. There are many guides available on the Astro documentation for all platforms you can imagine:

![Astro Deployment Guides](https://blog.logrocket.com/wp-content/uploads/2024/01/astro-deployment-guides.png)

We’ll look at the Vercel deployment process just for comparison. 

Similar to Docusaurus, the Starlight project can be deployed to Vercel as a static site by default. But if we need to have SSR capabilities too, we need to run the `npx astro add vercel` command. This will make the required modifications to the `astro.config.mjs` file to support SSR.

## Starlight and Docusaurus features

Now that we're clear on setting up the repositories and deploying them, let's take a look at the features that both of them provide.

### Docusaurus features

The Docusaurus site we created using the CLI has many features out of the box.

#### Doc pages

The startup example comes with several documentation pages. These are the pages that we can use to write our documentation. They are written in Markdown, which would be converted to a React component by [MDX](https://mdxjs.com/): ![Docusaurus Doc Pages](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-doc-pages.png) The docs currently show one article named “**Tutorial intro**” and two other collapsed menus named “**Tutorial - Basics**” and “**Tutorial - Extras**.” That is because the Docusaurus repository contains a `docs` folder with an `intro.md` file and two other folders. Docusaurus follows a file system-based routing structure that makes it easy to create nested pages.

#### Blog pages

The startup example also comes with a blog page. This page can be used to write blog posts, which could be considered announcements or updates related to our product:

![Docusaurus Blog Page Sample](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-blog-page-sample.png)

There are currently four blog posts available because the `blog` folder in the repository contains the respective files.

#### Sidebar and table of contents

The sidebar is a navigation menu that is shown on the left side of the page. It is automatically generated based on the file system. But we also have the option of supplying it manually by creating a `sidebars.js` file in the root of the repository. 

We can also see that we get an auto-generated table of contents on the right side of the page. This is a navigable menu that shows all the H2 and H3 headings on the current page:

![Docusaurus Navigation Menu](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-navigation-menu.png)

#### Dark mode support

On the top right corner of the page, we can also see a little sun icon. This is a toggle button that can be used to switch between light and dark modes. The implementation of the default dark mode is taken care of by Docusaurus out of the box:

![Docusaurus Dark Mode](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-dark-mode.gif)

### Starlight features

When it comes to Starlight, we can see some of the features that we saw in Docusaurus. Some features are missing and others are extra. Let’s explore them now.

#### Guides and references

Starlight introduces us to the concept of guides and references according to the [Diátaxis framework](https://diataxis.fr/how-to-guides/), where guides are supposed to be step-by-step instructions to accomplish an end goal. Relatedly, references are supposed to be a detailed comprehensive outline of what we're trying to document. Apart from this theoretical difference, there is no difference in the visual appearance of both of them in Starlight:

![Starlight Sidebar](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-sidebar.png)

#### Sidebar and table of contents

Similar to Docusaurus, Starlight also has a sidebar and a table of contents. It is automatically generated based on the file structure. But we can also supply it manually by editing the `starlight.sidebar` property in the `astro.config.mjs` file.

#### Dark mode support

Starlight also provides dark mode support out of the box. We can choose the mode to be light, dark, or a system default from the toggle on the top right of the page:

![Starlight Dark Mode](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-dark-mode.gif)

### Unique features

The features we explored above were the common, core features of Docusaurus and Starlight. Now, let’s look at some of the more unique features they offer.

#### Tabs and cards

Both Docusaurus and Starlight provide built-in components to create the tab layout where multiple variations of a step need to be presented:

![Docusaurus Tab Layout](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-tab-layout.png)

Starlight goes the extra mile and also provides built-in components to create cards and manage their layout as well:

![Starlight Components To Create Cards](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-components-create-cards.png)

#### Admonitions and asides

Both frameworks provide special components to emphasize certain blocks of text. In Docusaurus, they are known as admonitions while Starlight calls them asides. 

Here's how Docusaurus renders its admonitions:

![Docusaurus Admonitions](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-admonitions.png)

And this is how asides look in Starlight:

![Starlight Asides](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-asides.png)

To render these in both frameworks, we'll use this code inside our Markdown files:

```markdown
:::caution
If you are not sure you want an awesome docs site, think twice before using [Starlight](../../).
:::
```

The frameworks will take care of the rest.

#### Math support and diagrams

This is one aspect where Docusaurus takes the lead as it provides support for rendering math equations and diagrams out of the box. 

Math equations can be rendered by wrapping [Latex](https://www.latex-project.org/) equations between `$` symbols or by surrounding multiple lines between `$$` symbols. We just need to install the `remark-math` and `rehype-katex` plugins. 

We can also create diagrams inside of our documentation using [`mermaid.js`](https://mermaid.js.org/). Upon installing and enabling the Mermaid plugin, any code block with the language set to `mermaid` will be rendered as a diagram.

#### Front matter support

Both Docusaurus and Starlight support the front matter. It is used to provide additional metadata to the Markdown files. It is written at the top of the Markdown file between `---` symbols and is parsed as YAML. 

Several properties of the Markdown file can be overridden using front matter. For instance, the title of the page can be overridden using the `title` property. The `slug` or the browser URL can also be controlled from the front matter if required. Here’s an example of a Markdown file with front matter:

```markdown
---
id: doc-with-tags
title: A doc with tags
tags:
- Demo
- Getting started
---

The markdown goes here
```

Here are the [front matter properties that Docusaurus supports](https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-blog#markdown-front-matter). And here are the [Starlight ones](https://starlight.astro.build/reference/frontmatter/#_top).

#### Code editors with syntax highlighting

Both frameworks also support code blocks with syntax highlighting. Docusaurus uses [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) for theming, while Starlight uses an Astro package called [expressive-code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to control customizations.

#### Line highlighting

In Docusaurus, line highlighting is handled via special comments like `// highlight-next-line`, `highlight-start`, and `highlight-end` and also by specifying the line numbers at the top of the code block. 

In Starlight, this can be accomplished with the line number range as well as using string matching. For example, including `"var a = 10"` at the top of the code block will highlight that string. 

This even works with RegEx. Special formatting can also be applied to show lines that were inserted or deleted if we want to represent a diff between the `before` and `after` states of a code block. Take a look at the following block in Starlight:

![Starlight Code Block](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-code-block.png)

This code block will show up like so:

![Starlight Return Statement Code Block ](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-code-block-return-statement.png)

#### Line numbering

Docusaurus provides the option to display line numbers in the block of code by specifying the `showLineNumbers` property at the top of the code block.

#### Code block frames

Starlight provides the capability to change the appearance of the code block window by specifying the `title` property at the top of the code block or by providing a filename as the first comment in the code block.

## Customization capabilities

Those were the inbuilt capabilities offered by the frameworks. In addition to that, we are also provided with several options through which we can customize the appearance of our site from scratch.

### Custom CSS

We can customize the appearance of our site by writing custom CSS. Both frameworks provide a way to do this. 

In Docusaurus, we can supply it as the `theme` key inside of the `docusaurus.config.js` file under presets:

```javascript
{
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
}
```

Then, we can write all our custom CSS inside of the `custom.css` file. Docusaurus will make that CSS globally available throughout the site. In addition to that, we can modify the CSS linked to the existing CSS classes by targeting [theme class names](https://docusaurus.io/docs/styling-layout#theme-class-names). 

We can also change the value of the CSS variables in the `custom.css` file to change the appearance of the site as we like. For example, if we want to change the primary color for the dark mode, we could do something like this:

```css
[data-theme='dark'] {
--ifm-color-primary: #4e89e8;
}
```

Similarly, in Starlight, we can create a custom CSS file in our source directory and then supply its path in the `astro.config.mjs` file:

```css
{
  integrations: [
    starlight({
      title: 'Docs With Custom CSS',
      customCss: [
        './src/styles/custom.css',
      ],
    }),
  ],
}
```

Like Docusaurus, Starlight's default look can be modified by changing the values of the color palette variables:

```css
:root[data-theme='light'] {
--sl-color-accent-low: #c2dbed;
--sl-color-accent: #0073aa;
}
```

### Override components

Both frameworks also provide capabilities to override the default look of the different aspects of the site. 

Docusaurus provides us with what it calls [Swizzling](https://docusaurus.io/docs/swizzling#overview). It is the capability to eject a particular component like the sidebar or footer so that we get access to the source code of that component in our repo. Then, we can modify it to suit our preferences and it will reflect on our site. 

Starlight provides a similar capability called [component overrides](https://starlight.astro.build/guides/overriding-components/). The process to accomplish this is a little different. We need to create a new Astro component based on our preferences and then supply it in the `astro.config.mjs` file as an override:

```javascript
{
  integrations: [
    starlight({
      title: 'Custom site',
      components: {
        SocialIcons: './src/components/MyComponent.astro',
      },
    }),
  ],
}
```

This example overrides the `SocialIcons` component with our custom component.

### Custom components

In addition to those customization options, both frameworks provide the capability of creating entire pages from scratch. 

In Docusaurus, we can create a new page by creating a new file in the `src/pages` folder. Then, we can write the contents of the React page. 

For example, the homepage that we get when we create a new Docusaurus site is a React component. It comes up at the `/` route because there is a file named `index.js` in the `src/pages` folder. We can extend this by creating more pages. For example, say we create a file named `about.js`:

```javascript
import React from 'react';

export default function About() {
  return (
    <div className="about">
      <h1>About page</h1>
      <p>This is created with Docusaurus!</p>
    </div>
  );
}

```

Then, we can access it at the `/about` route:

![About Page Created With Docusaurus](https://blog.logrocket.com/wp-content/uploads/2024/01/about-page-docusaurus.png)

Starlight does not directly provide this capability but we can use it indirectly via MDX. We can create a new Astro component inside the `src/components` folder called `about.astro`:

```jsx
<div>
  <p>This is created with Astro!</p>
</div>
```

Then, we can create a new MDX file inside the `docs/guides` folder called `about.mdx`:

```markdown
---
title: About page
description: This is a page created with an Astro component
---

import About from '../../../components/about.astro';

<About />
```

Then, we can access it at the `/guides/about` route:

![Starlight About Page](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-about-page.png)

Note that for the **About page** to show up in the sidebar, we need to delete the sidebar config from the `astro.config.mjs` file so that it is auto-generated. This feature to write React components directly within Markdown documents is a functionality provided by MDX. So, it is also supported in Docusaurus.

## Performance and SEO

Because both Docusaurus and Starlight are static site generators, they are quite performant out of the box. Starlight also has the added advantage of opting into SSR if required. Let’s take a look at the performance metrics of both frameworks by running Lighthouse.

### Reviewing Docusaurus performance

When we run Lighthouse on the homepage of our startup example, we get the following results:

![Docusaurus Performance Review](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-performance-review.png)

These are pretty good results – all the scores are above 90\. When we try to run the same test on a content page instead of the homepage that was built with React, we get this: ![Docusaurus Content Page Performance](https://blog.logrocket.com/wp-content/uploads/2024/01/docusaurus-content-page-performance-review.png) This time, the Largest Contentful Paint (LCP) suffers, but still gives a decent score above 80.

### Reviewing Starlight performance

When we run Lighthouse on the homepage of our startup example, we get the following results:

![Starlight Performance](https://blog.logrocket.com/wp-content/uploads/2024/01/starlight-performance.png)

The scores observed are comparable to those of Docusaurus. Similarly, for Starlight, both the homepage and content page yield nearly identical scores. This may be because the homepage is also built with MDX and not React as was the case with Docusaurus.

## Conclusion

Both Docusaurus and Starlight are great frameworks for building documentation websites. Docusaurus is more mature and has the advantage of being a stable release (3.0) while Starlight is still in beta at the time of writing this article. But Starlight has the advantage of being built on top of Astro and thus, being able to use the latest features of the web platform. 

Throughout this article, we observed that Starlight is nearly on par with Docusaurus regarding features. However, Starlight stands out for its flexibility in allowing custom components in your preferred framework. Docusaurus is the better choice for those seeking a more established solution, especially if math or diagram rendering is essential. Both options are good choices depending on your specific needs.

---

##Get set up with LogRocket's modern error tracking in minutes:

1. Visit https://logrocket.com/signup/ to get an app ID.
2. Install LogRocket via NPM or script tag. `LogRocket.init()` must be called client-side, not server-side.

NPM:
```bash
$ npm i --save logrocket 

// Code:

import LogRocket from 'logrocket'; 
LogRocket.init('app/id');
```
Script Tag:
```javascript
Add to your HTML:

<script src="https://cdn.lr-ingest.com/LogRocket.min.js"></script>
<script>window.LogRocket && window.LogRocket.init('app/id');</script>
```

3.(Optional) Install plugins for deeper integrations with your stack:
*   Redux middleware
*   ngrx middleware
*   Vuex plugin

[Get started now](https://lp.logrocket.com/blg/signup)