5 ms·

Comparing Docusaurus and Starlight and why we made the switch

58 points by pmig 1y ago

willwade 1y ago
Particularly like the honest take. I wouldn’t say reading this I’d go for starlight either > When I tried to create marketing pages with Starlight in addition to the technical documentation, I nearly gave up. Coming from the Docusaurus world, this wasn't an issue as the starter template comes with a front page and a blog out of the box. You can even create multiple documentations on different paths. We used /docs, for example. > Starlight, on the other hand, is only built for documentation and not for marketing pages. It even took an ugly hack to make sure the default path is /docs and not /. > Please don't look at this custom script configured in our astro.config.mjs we need to execute on every page to make sure that the redirection works properly Love the straight talking. Refreshing in the period of ai slop blogposts
- SOLAR_FIELDS 1y ago
  They actually hand wave and gloss over two of the other biggest drawbacks: - Starlight is 6 years less mature than docusaurus - the people who maintain starlight have some level of billions less at their disposal to keep the project going. If Astro and the company behind it go belly up now you have a new problem on your hands The main appeal I can see is for someone who wants a lot more extensibility and control over the design aspect of their docs. For those who just need to slap some pretty good looking docs into a well supported framework for the next 10 years would do better with the more battle tested framework supported by BigCorp
  - ValentineC 1y ago
    > the people who maintain starlight have some level of billions less at their disposal to keep the project going. If Astro and the company behind it go belly up now you have a new problem on your hands Starlight and Docusaurus aren't much different in this aspect. Meta could decide to stop paying slorber (the main maintainer of Docusaurus) at any time. I hear from friends in Meta that Docusaurus isn't even widely used internally. Both projects are MIT-licensed, at least, and that's a plus for continuity if someone ever wants to fork them.
    - ascorbic 1y ago
      Disclosure: Astro core team Yes, the difference here is that Astro considers Starlight to be a core part of our project. We use it for our own docs, as well as it being the basis for a significant percentage of our users' sites. I've no reason to believe Docusaurus's funding is in any danger, but I think the Open Collective that pays for full time Starlight development is probably a more dependable source of funding than Meta.
- quintu5 1y ago
  This has been my initial experience as well. I was kind of disappointed to find that starlight is meant to be tore entire site instead of part of a larger Astro site, which would be so nice.
  - MortyWaves 1y ago
    There is no real reason you can't have a monorepo, with one project being the Astro site and the other Starlight docs.
    - quintu5 1y ago
      True. It just limits the utility of it being built on top of Astro.
MrDarcy 1y ago
For documentation versioned docs are critical. Docusaurus handles multiple versions extremely well, curious if the author has released a new major version of Glasskube and if not, will they miss this feature in the future.
- pmig 1y ago
  It's a good point. I am personally not really a fan of versioned docs. Having a CHANGELOG.md or similar is critical, but how often do you really want to explore the docs in a specific version? And there are also way better options to pinpoint changes. You can think of using git blame instead of clicking through a dozen of point releases of your versioned docs.
  - IanCal 1y ago
    > but how often do you really want to explore the docs in a specific version? Absolutely any time I'm not using the latest version?
    - Aeolun 1y ago
      I think the idea is that you shouldn’t ever do that?
      - IanCal 1y ago
        Never use anything other than the absolute bleeding edge immediately after release? That's frankly wild, and totally ignores that many people release new versions while supporting older ones for transition.
        0cf8612b2e1e 1y ago
        Here I am on my 10+ year old database version thinking, “Damn, why didn’t I think to just not use this thing anymore?”
      - joseda-hg 1y ago
suryao 1y ago
For writing technical styled documentation, I've found fumadocs to be amazing. It looks great out of the box and supports a product switcher, which can be used for maintaining related products or product versions. It also supports OpenAPI imports and API playgrounds. The best part is that it is just a fully fledged (nextjs) app that is entirely customizable with relative ease. We just moved to it from Docusaurus and couldn't be happier.
- michaelermer 1y ago
  Same here, funadocs also integrates OpenAPI seamlessly and you can use blocks of the OpenAPI operations in your actual documentation which is perfect for writing developer guides.
quintu5 1y ago
Regarding the author’s mention of starlight missing support for mermaid — shouldn’t they be able to just use mermaidjs to render those charts? Why the need for playwright or a plugin?
rxliuli 1y ago
I haven't used Starlight, but Docusaurus is very slow. The last time I used it, its performance on a large documentation site was terrible, even causing the GitHub Actions Runner to time out. In other words, a single build took over 30 minutes. I never considered using it again after that.
swyx 1y ago
> To be completely honest: The reason I looked for another documentation framework was that I was fed up with Docusaurus taking forever to start the initial development server. With the latest Node version (24), Docusaurus version (3.7), and React version (19), it took a little over 5 seconds to start the development server. Although this number doesn't seem to be that high, it was a lot higher with previous versions. I remember waiting over 20 seconds for the development server to start, which really frustrated me. what is the cause for this?

58 points by pmig 1y ago

Particularly like the honest take. I wouldn’t say reading this I’d go for starlight either > When I tried to create marketing pages with Starlight in addition to the technical documentation, I nearly gave up. Coming from the Docusaurus world, this wasn't an issue as the starter template comes with a front page and a blog out of the box. You can even create multiple documentations on different paths. We used /docs, for example. > Starlight, on the other hand, is only built for documentation and not for marketing pages. It even took an ugly hack to make sure the default path is /docs and not /. > Please don't look at this custom script configured in our astro.config.mjs we need to execute on every page to make sure that the redirection works properly Love the straight talking. Refreshing in the period of ai slop blogposts

SOLAR_FIELDS 1y ago
They actually hand wave and gloss over two of the other biggest drawbacks: - Starlight is 6 years less mature than docusaurus - the people who maintain starlight have some level of billions less at their disposal to keep the project going. If Astro and the company behind it go belly up now you have a new problem on your hands The main appeal I can see is for someone who wants a lot more extensibility and control over the design aspect of their docs. For those who just need to slap some pretty good looking docs into a well supported framework for the next 10 years would do better with the more battle tested framework supported by BigCorp
- ValentineC 1y ago
  > the people who maintain starlight have some level of billions less at their disposal to keep the project going. If Astro and the company behind it go belly up now you have a new problem on your hands Starlight and Docusaurus aren't much different in this aspect. Meta could decide to stop paying slorber (the main maintainer of Docusaurus) at any time. I hear from friends in Meta that Docusaurus isn't even widely used internally. Both projects are MIT-licensed, at least, and that's a plus for continuity if someone ever wants to fork them.
  - ascorbic 1y ago
    Disclosure: Astro core team Yes, the difference here is that Astro considers Starlight to be a core part of our project. We use it for our own docs, as well as it being the basis for a significant percentage of our users' sites. I've no reason to believe Docusaurus's funding is in any danger, but I think the Open Collective that pays for full time Starlight development is probably a more dependable source of funding than Meta.
quintu5 1y ago
This has been my initial experience as well. I was kind of disappointed to find that starlight is meant to be tore entire site instead of part of a larger Astro site, which would be so nice.
- MortyWaves 1y ago
  There is no real reason you can't have a monorepo, with one project being the Astro site and the other Starlight docs.
  - quintu5 1y ago
    True. It just limits the utility of it being built on top of Astro.

MrDarcy 1y ago

For documentation versioned docs are critical. Docusaurus handles multiple versions extremely well, curious if the author has released a new major version of Glasskube and if not, will they miss this feature in the future.

pmig 1y ago
It's a good point. I am personally not really a fan of versioned docs. Having a CHANGELOG.md or similar is critical, but how often do you really want to explore the docs in a specific version? And there are also way better options to pinpoint changes. You can think of using git blame instead of clicking through a dozen of point releases of your versioned docs.
- IanCal 1y ago
  > but how often do you really want to explore the docs in a specific version? Absolutely any time I'm not using the latest version?
  - Aeolun 1y ago
    I think the idea is that you shouldn’t ever do that?
    - IanCal 1y ago
      Never use anything other than the absolute bleeding edge immediately after release? That's frankly wild, and totally ignores that many people release new versions while supporting older ones for transition.
      - 0cf8612b2e1e 1y ago
        Here I am on my 10+ year old database version thinking, “Damn, why didn’t I think to just not use this thing anymore?”
    - joseda-hg 1y ago

suryao 1y ago

For writing technical styled documentation, I've found fumadocs to be amazing. It looks great out of the box and supports a product switcher, which can be used for maintaining related products or product versions. It also supports OpenAPI imports and API playgrounds. The best part is that it is just a fully fledged (nextjs) app that is entirely customizable with relative ease. We just moved to it from Docusaurus and couldn't be happier.

michaelermer 1y ago
Same here, funadocs also integrates OpenAPI seamlessly and you can use blocks of the OpenAPI operations in your actual documentation which is perfect for writing developer guides.

quintu5 1y ago

Regarding the author’s mention of starlight missing support for mermaid — shouldn’t they be able to just use mermaidjs to render those charts? Why the need for playwright or a plugin?

rxliuli 1y ago

I haven't used Starlight, but Docusaurus is very slow. The last time I used it, its performance on a large documentation site was terrible, even causing the GitHub Actions Runner to time out. In other words, a single build took over 30 minutes. I never considered using it again after that.

swyx 1y ago

> To be completely honest: The reason I looked for another documentation framework was that I was fed up with Docusaurus taking forever to start the initial development server. With the latest Node version (24), Docusaurus version (3.7), and React version (19), it took a little over 5 seconds to start the development server. Although this number doesn't seem to be that high, it was a lot higher with previous versions. I remember waiting over 20 seconds for the development server to start, which really frustrated me. what is the cause for this?