Build a Manual with Docusaurus #6: Maintenance — Search, Accessibility, and Documentation Culture

Framework Docusaurus Documentation Static Site
4 min read

By the time you reach #5, you have docs equipped with multiple languages and versions. The building stage is now over. Documentation isn’t something you make once and finish; it keeps growing alongside the product. In this final post we cover the operations that keep those docs alive over time.

This series, Build a Manual with Docusaurus, runs in six parts.

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

In this post we’ll lay out three things: adding search, accessibility for everyone, and the culture that keeps docs alive.

Adding Search #

Here we finish the search we deferred in #2. We said there were two paths.

The first is Algolia DocSearch. Apply, then put the values you receive into themeConfig in docusaurus.config.js, and you’re done.

docusaurus.config.js — Algolia search 
themeConfig: {
  algolia: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX',
  },
}

The second is the local search plugin. Since it builds an index at build time and works without any external service, it’s convenient for internal or Korean-language docs.

Install the local search plugin 
npm install @easyops-cn/docusaurus-search-local

After installing, register the plugin in docusaurus.config.js and a search box appears. For public open source, Algolia generally fits well; for private, internal docs, the local plugin does.

Accessibility for Everyone #

Documentation should be readable by as many people as possible. Docusaurus themes have decent accessibility by default, but there are a few spots that break easily during writing.

  • Don’t skip the heading hierarchy. You should step down one level at a time so screen readers read the structure correctly.
Keeping 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. Drawing diagrams with Mermaid keeps them as text, so you’re free of this problem.
  • Maintain color contrast. When tweaking theme colors, check that the contrast between body text and background exceeds the WCAG AA standard (4.5:1).

The Culture That Keeps Docs Alive #

Even with a good documentation tool, once updates stop, docs quickly become lies. What long-lived docs have in common isn’t the tool but the habit.

The key is upholding the Docs as Code approach 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 a feature. If you make “update the docs” part of the definition of done, code and docs drift apart less often.

Add a few more things to this. Surface each post’s last-modified date so old posts are easy to find; check for broken links at the build stage (Docusaurus catches broken internal links at build time by default); and rather than putting off a big overhaul, fix things small and often. Steady small updates keep docs alive better than one perfect cleanup.

Closing the Series #

Over six parts we built a documentation site with Docusaurus, from start to operations. We installed it (#1), structured it with the sidebar and search (#2), filled in the content with code blocks and admonitions (#3), deployed to Cloudflare Pages (#4), added multiple languages and versions (#5), and finally arrived at how to maintain it over time (#6).

If a blog is a chronological collection of posts, a documentation site is a structured reference. That difference shaped everything, from the choice of tool to the operational habits. Now I hope you’ll put your own team’s docs on top of this flow.

X