Starlight
This month I had the opportunity to take Starlight for test drive as a demo for my team’s internal documentation. Although Starlight currently comes with a warning that it’s in early development, we were impressed by its polish and features. I think it has real potential to challenge established documentation SSGs like VitePress or Docusaurus.
If you already have Markdown files, it is absurdly easy to publish them with Starlight. Those are basic table stakes for any SSG, though. If you need to do something unusual in your docs site, such as host an API or enforce authentication, good news! Starlight is built on Astro, so you have the full power of Astro and its integrations at your disposal. For our demo, I enabled diagrams with the astro-diagram plugin. Like any Astro site, you can create components in Astro’s syntax or any supported framework including React, Preact, Svelte, Vue, SolidJS, AlpineJS and Lit.
Documentation is not worth much if the content is not discoverable. You can configure the sidebar manually or just point a sidebar section at a directory, which is nice. But Starlight’s pièce de résistance IMO is the excellent static site search courtesy of Pagefind, and I’m already a fan. Other solutions in this space don’t have a built-in search, have a very minimal search UI, or rely on an external service like Algolia.
The drawback of Starlight, aside from its wet-behind-the-ears newness, is the inflexibility. There’s no way to make a custom page that uses the Starlight’s layout, as of today. You can only have one sidebar, so this might make certain kinds of documentation difficult or impossible. VitePress supports multiple sidebars if that’s a deal breaker. It is certainly difficult to balance simplicity with customizability.
For our use case, we ultimately decided against using Starlight in favor of GitHub’s wiki feature. It might look comparatively boring and have a terrible search UX, but GitHub’s wiki edit and publish workflow is good enough for internal documentation. Besides, access is already restricted to the team members, something we’d have to replicate somehow with Starlight.