Why I use Starlight for my docs
All the documentation for the libraries and plugins I maintain uses Starlight.
And if, like me, you develop tools for developers, libraries, or any project that needs documentation, I recommend you use it too.
But reaching this conclusion took me longer than I'd like to admit.
I tried many alternatives, spent hours configuring each one, and even considered building my own documentation framework.
The problem wasn't a lack of options, but rather that I didn't know what I wanted.
It was through that trial and error process that I discovered what really matters to me in documentation.
In this article I'll cover:
- What I look for in good documentation.
- The alternatives I tried before landing on Starlight (and why I discarded them).
- What makes Starlight my definitive choice.
What I look for in good documentation
At first, every new tool I tried seemed promising.
But after using it and maintaining it for a while, the cracks always appeared.
Over time, I started noticing patterns. There were things that frustrated me over and over, and others that made everything flow effortlessly.
These are the priorities that ended up being decisive.
Just write Markdown
I want to write Markdown and forget about the rest.
At most, some minimal configuration if necessary, but I don't want to maintain code or track changes in things that aren't content.
Extensible without cluttering the docs
If I need extra functionality, I want to add it without putting code inside the documentation project.
Ideally, through plugins or integrations that I can reuse in other projects.
Custom components with Tailwind CSS
Sometimes I need to create landing pages or more visual sections within the documentation, and for that I want to use custom components with Tailwind CSS.
Similar to the previous point, I want to add these components through a library that I can reuse in other projects.
Static generation
Documentation sites are, by nature, static.
The content doesn't change based on who visits it and doesn't require a database running on a server.
Static generation means instant loading speed, excellent SEO, and the ability to host the site anywhere without complications.
The alternatives I tried before landing on Starlight (and why I discarded them)
I tried more options than I'll mention here, but these three were the ones I seriously considered.
Protocol
Protocol is a Tailwind Plus template, and it has the most beautiful design I've seen for documentation.
But that's where the good ends.
Protocol comes with too much code you have to maintain yourself.
There's no plugin system or way to extend it without getting your hands into the base code.
For a small project it might work, but when you have several documentation sites to maintain, it becomes unsustainable.
VitePress
VitePress was a very close second place.
The default interface is beautiful, I even like it more than Starlight's.
It's extensible, static generation is excellent, and the development experience is very smooth.
The problem came when I tried to integrate Tailwind to create custom components.
I never got it to work, not even with some alternative solutions I found on the internet.
Fumadocs
Fumadocs is, in my opinion, the best React-based framework for technical documentation right now.
It's very good, very complete, and has an attractive design. It's a shame it's not more popular because it honestly deserves it.
However, like Protocol, it comes with a lot of code you have to maintain.
And although it's customizable, it doesn't have a real plugin system that lets you extend it without touching the project's base code.
What makes Starlight my definitive choice
Starlight meets all my priorities, but not perfectly from the start.
And that, paradoxically, is part of what makes it perfect.
The design isn't my favorite, but it's extensible
Being honest, I prefer the design of VitePress or Protocol.
It's not that Starlight is ugly, it's simply a matter of personal taste.
But this is where extensibility shines: I created Starlight UI Tweaks to adjust the design to my liking.
I extended some components, completely changed the design of others, and if I need to in the future, I can modify the typography, colors, spacing, and any other detail.
It lacks features I want, but I can add them
Starlight doesn't include all the functionality I want to offer my users a better experience.
For example, in recent months "page actions" have become popular in documentation: copying content in Markdown, opening it directly in a chat with an LLM, among other options.
Starlight doesn't include these features natively, which is why I created Starlight Page Actions.
Additionally, there's a broad ecosystem of community-maintained plugins that cover many other common needs.
Just Markdown, no complications
You write your Markdown, adjust a couple of optional configurations if you need to, and everything works.
There are no complex configuration files, code to maintain, or anything to track beyond the content.
Custom components when I need them
Since Starlight is built on top of Astro, I can create custom components with Tailwind CSS for landing pages or marketing sections.
In fact, I have a component library designed specifically for Starlight that I reuse across all my documentation sites.
Static generation guaranteed
Being built on Astro, static generation comes by default.
Ultra-fast sites, optimized SEO, and free hosting anywhere.
Final reflections
I spent months trying alternatives, configuring, discarding, and starting over.
In the end, the answer wasn't finding the perfect tool, but finding the tool that would let me make it perfect for me.
Starlight gives me exactly that: a solid foundation that doesn't force me into anything, but allows me everything.
For you, it might not be Starlight. Maybe it's VitePress, Fumadocs, or even something I discarded. Everyone has to walk their own path and discover what priorities are truly important for their case.
But if your priorities are similar to mine, give Starlight a chance. It will probably save you the path I already walked.