Comparing docs site builders: VuePress vs Starlight

VuePress has been my go-to documentation site framework for several years (the zsh-abbr docs are an example). A few months ago Starlight, a documentation site framework by Astro, was released. I like the Astro docs’ UI, so when I next sat down to build a documentation site (the zsh-test-runner docs) I tried Starlight.

For the casual developer, I would recommend Starlight over VuePress on the merit of its search feature alone: it takes no configuration, a significant DX improvement over my VuePress setup (see Algolia Search in VuePress Without Joining DocSearch). And between Starlight and VuePress, Starlight is the only choice if you need components written in frameworks other than Vue; even if you need only Vue components, Starlight is worth considering — adding Vue components to Starlight takes a little less boilerplate than does adding Vue components to VuePress. But if you need to customize things, whether it’s something small like putting a link to the CHANGELOG in the header nav, something large like giving your site a blog theme, or something in between, go with VuePress.

Here are the differences that stand out to me:

Contents

JS frameworks

Both VuePress and Starlight support Vue components.

Starlight, like Astro, supports other JS frameworks besides Vue.

In VuePress you have to go over some (short) hurdles to register Vue components.

Winner: Starlight if your project needs to support non-Vue components. Otherwise, up for debate.

Search

Starlight uses Pagefind. Search is enabled automatically and requires zero configuration

VuePress supports Algolia DocSearch. Search requires additional integration work. But once configured you have all the control —weighting, synonyms, etc— that comes with DocSearch or (if you, like me, use VuePress DocSearch without the DocSearch service) standard Algolia.

Winner: Starlight unless you want to fiddle with your search index.

Navbar

Starlight supports icon-only links to a predefined set of accounts.

VuePress supports fully customizable navbar links, including dropdown menus.

Winner: VuePress.

Sidebar

Starlight uses a two-sidebar model. The primary sidebar lists the site’s pages. The secondary sidebar lists the current page’s headings. In the table of contents sidebar, the current section is highlighted; the highlight updates continuously on scroll. For the last item in the sidebar, scroll-based highlighting only works if the section is tall enough for the heading to reach the top of the page when the page is fully scrolled (if the last section on the page is short, its sidebar item will never be highlighted). The table of contents sidebar includes, in addition to links to the page’s headings, a link to “Overview” which brings users to the top of the page. The table of contents sidebar can be disabled site-wide or on a per-page basis, but space is reserved for it whether it’s enabled or not.

VuePress uses a single unified sidebar for both pages and the current page’s table of contents. The sidebar content is dynamic, showing the current page’s contents and hiding all other pages’ contents. The current section is highlighted; the highlight updates when scrolling stops.

Winner: VuePress. Starlight’s “Overview” links and its reserving space for the disabled secondary sidebar are shortcomings, and the scroll-based highlighting is buggy.

Markdown

Starlight supports, in addition to standard Markdown features, four admonition levels (called “asides”), and MDX. In MDX you can use components written in Astro and the other frameworks Astro supports; Starlight ships with components for tabbed content, two kinds of cards, and icons.

VuePress supports, in addition to standard Markdown features: - linked section headings - three admonition levels (called “custom containers”) - accordions (the “details” custom container, named after <details>) - badges - tabs within code blocks (”code groups”) - line numbers in code blocks - highlighted lines in code blocks. - customization of Markdown features - customization of the custom containers

Winner: Starlight if you need MDX. VuePress has more features.

Customization

Starlight supports minimal configuration.

VuePress is highly configurable. One of the configurable options is what theme to use; the default theme is highly configurable, and there is an API for authoring themes. VuePress also supports plugins. There are many official plugins (see the Official Plugins Reference sidebar links here), and many community plugins (those by Mr. Hope are good examples); use the plugin API to author your own.

Winner: VuePress if you want to customize your site.

Accessibility

Starlight has a “skip to content” link before the header. VoiceOver (tested with Safari) announces the custom keyboard shortcut, which opens the search dialog. The search hits section is not ARIA live. Search hits are tabbable, and VoiceOver reads the selected hit’s page title. After the search box is closed, focus returns to where it was before the search box was opened. VoiceOver announces the selected theme on focus and on change.

VuePress does not have a skip link. VoiceOver does not announce the custom keyboard shortcut which opens the search dialog. Search hits section is not ARIA live. Search hits are tabbable, but VoiceOver is silent when a search hit gets focus. After the search box is closed, focus goes to the top of the page. VoiceOver does not announce the selected theme or changes to it.

Winner: Starlight.