[HN Gopher] Comparing Docusaurus and Starlight and why we made t...
___________________________________________________________________
Comparing Docusaurus and Starlight and why we made the switch
Author : pmig
Score : 35 points
Date : 2025-05-23 17:15 UTC (4 days ago)
(HTM) web link (glasskube.dev)
(TXT) w3m dump (glasskube.dev)
| willwade wrote:
| 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 wrote:
| 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
| quintu5 wrote:
| 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.
| MrDarcy wrote:
| 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 wrote:
| 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 wrote:
| > 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?
| MrDarcy wrote:
| > how often do you really want to explore the docs in a
| specific version?
|
| All the time. It's inevitable. If you ever sell software in
| the tools / configuration / package management space to "the
| enterprise" (which I think you do) then some of your biggest
| customers are going to be stuck on old versions. They'll need
| to easily select the version they're running if only to
| figure out how to upgrade to the version you want them to be
| running.
|
| Edit: To clarify and drive the point home, in a previous life
| I was at a startup that sold something like Glasskube to
| enterprises. Version 3 of our software was significantly more
| performant and had some desirable features compared to
| version 2. Many of our largest paying customers literally
| called us up and asked us for help upgrading them. In that
| situation it was invaluable for our own CEO and pro services
| team to pull up version 2 docs side-by-side with version 3
| docs, pull up a copy of the customer's code, then plan the
| migration for them step by step. This resulted in both
| revenue from the professional services and revenue from the
| license expansion as the customer scaled out on version 3.
|
| So, versioned docs aren't just for customers, they're also
| for you, your developers (who may need to patch an old
| version or develop a migration tool), and your service
| delivery team.
| ramoz wrote:
| Literally every day when working on any type of data
| science or ML task
| pixelready wrote:
| The versioned docs for both MUI and Tanstack Query have been
| very helpful in recent projects I'm working on. Obviously
| versioned docs are only valuable against major / breaking
| changes. Changelog is sufficient for non-breaking stuff.
|
| I also really like sites that have site wide settings for
| code examples in different available languages, package
| managers, etc. I know this must be a maintenance burden on
| the teams of those projects but boy do I appreciate it as an
| implementer.
| dumah wrote:
| It's wild that you are offering your views on software
| documentation while you think checking git blame is a
| substitute for retaining documentation, and you don't
| understand why users would want documentation for old
| versions.
| tacker2000 wrote:
| Are you serious? In the real world, people dont update
| software as soon as a new version comes out. Sometimes I am
| still using an age old version of an app or a framework
| because the client doesnt want to pay to upgrade, there are
| dependencies, or whatever...
|
| Having easily accessible documentation for the older versions
| is a must, for anything that is remotely "serious".
|
| Just check the Laravel docs for example, or Vue, etc...
| suryao wrote:
| 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.
| quintu5 wrote:
| 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?
___________________________________________________________________
(page generated 2025-05-27 23:00 UTC)