How does shipyard compare to Docusaurus and Astro Starlight? This page provides an honest assessment of each tool’s strengths and limitations.
Note: This comparison reflects the state of these tools as of December 2025. All three projects are actively developed, so features may have changed since this was written. When in doubt, check the official documentation.
Docusaurus is one of the best page builders out there. Despite its name suggesting it’s only for documentation, you can build all kinds of pages with it. The beauty is that content is stored within the codebase, so an AI assistant can manage the entire site—content, layout, everything.
Custom functionality is hard. Need to organize events with nice filtered views? Want to manage arbitrary data beyond docs and blog posts? You’ll find yourself fighting the framework. Astro’s content collections make this trivial—you can manage arbitrary data in Markdown and JSON files, then filter, transform, and render pages based on that data with ease. This flexibility simply doesn’t exist in Docusaurus without massively extending the default functionality.
The SPA approach is heavy-handed. Docusaurus ships a bloated JavaScript bundle as a single-page application. For content-focused sites, this is overkill. Astro’s approach—static HTML with no JavaScript by default—is much leaner and faster.
React-focused. If you prefer simpler templating, Docusaurus doesn’t offer an alternative. Astro components have a simpler syntax and produce clean static output.
Infima CSS is stagnating. Docusaurus uses Infima, their custom CSS component library (GitHub). While they’ve tried to make it reusable, development effort has stalled. It’s not really usable for elaborate custom styling beyond the defaults.
Astro itself is excellent—lean, flexible, and powerful. But it’s very bare-bones. You need a page builder to get started quickly.
The default page builder for Astro is Starlight, and it’s a solid choice for pure documentation sites.
Docs functionality is hardcoded. You cannot use Starlight’s templating, design, and navigation without also using its docs system. In Docusaurus, you can have the nice styling and easy structure without using docs at all—just a marketing site or blog. Starlight is built specifically for documentation—using it for other purposes requires workarounds.
Blog is a hacky workaround. Getting a blog working in Starlight requires a third-party plugin like starlight-blog by HiDeoo. It works, but it’s wiggling blog functionality into a docs-focused system rather than having cleanly separated concerns.
Navigation customization is limited. Want to add custom links to the top navigation bar? Starlight doesn’t support this out of the box. You’ll need component overrides or third-party plugins like starlight-utils. In shipyard, navigation is fully configurable from the start.
Undocumented component library. Starlight built their own component library that isn’t open-sourced as a standalone project, documented, or designed for extension. If you want to build on top of it, you’re on your own.
shipyard takes a different approach: composable building blocks on Astro.
The key difference is flexibility. shipyard doesn’t assume you’re building a documentation site—it gives you the tools to build whatever you need.
See also: Docusaurus Feature Parity Roadmap for a detailed comparison of supported features.