Build a Manual with Starlight #6: Maintenance — Search, Accessibility, Docs Culture

Framework Starlight Documentation Static Site
3 min read

By the time you reach #5, you have docs equipped with multilingual support and versioning. The building stage is now done. Docs are not made once and finished; they keep growing alongside the product. In this final post we cover the operations that keep those docs alive for the long run.

This series is Build a Manual with Starlight, in six parts.

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Docs
  • #3 Writing Content — Code Blocks, Mermaid, asides
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, Docs Culture ← this post

In this post we go over three things: search, accessibility for everyone, and the culture that keeps docs alive.

Search Needs Little Attention #

As we saw in #2, Starlight’s search has Pagefind built in by default. Unlike other tools that had you bolt search on separately or tweak tokenization, Starlight makes search work as soon as you build, and it handles several languages including Korean fine. From an operations standpoint, it is the part that needs the least attention.

Accessibility for Everyone #

Docs should be readable by as many people as possible. Starlight takes accessibility seriously and its defaults are solid, but there are a few spots that are easy to break while writing.

  • Do not skip heading levels. You have to step down one level at a time so that screen readers read the structure correctly.
Keep the heading hierarchy 
# Page title (h1, one per page)
## Major section (h2)
### Minor section (h3)
  • Link text should make sense on its own. Write the destination, like “installation guide,” rather than “click here.”
  • Add alt text to images. If you draw diagrams with Mermaid, they are text, so you are free of this problem.
  • Keep color contrast. When tweaking theme colors, check that the contrast between text and background exceeds the WCAG AA standard (4.5:1).

The Culture That Keeps Docs Alive #

Even with good doc tooling, once updates stop, docs quickly become lies. What long-lived docs have in common is not the tool but the habit.

The key is to uphold the Docs as Code we took as our starting point in #1 all the way through. Keep the docs in the same repository as the code, and fix the related docs within the same pull request that changes the feature. If you put “update the docs” into your definition of done, code and docs drift apart less.

Add a few things on top of that. Surface a last-modified date on each page to make stale pages easy to find, check for broken links during the build step, and fix things small and often rather than putting off big overhauls. Steady small updates keep docs alive better than one perfect overhaul.

Closing the Series #

Across six posts, we built a documentation site with Starlight from the ground up through operations. We installed it (#1), structured it with the sidebar and search (#2), filled it with code blocks and asides (#3), deployed it to Cloudflare Pages (#4), added multilingual support and versioning (#5), and finally arrived at keeping it alive for the long run (#6).

With that, we have covered all four tools — Hugo, MkDocs, Docusaurus, and Starlight — through the same flow. Which tool fits your team is laid out in the Documentation Site Generators Compared post, so if the choice is on your mind, start with that one. Now you can put your own team’s docs on this flow.

X