Build a Manual with Docusaurus #2: Sidebar and Search — Structuring Your Documentation

Framework Docusaurus Documentation Static Site
3 min read

In #1 we served our first doc with Docusaurus. When there are only one or two pages, structure isn’t a problem. The problem comes when docs grow into dozens of pages. A manual must always let the reader know “where the item I’m looking at fits in the whole.” The things that do that job are the sidebar and search.

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 ← this post
  • #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

In this post we’ll set up the sidebar automatically and manually, and lay out your options for adding search.

The Sidebar Is Defined in sidebars.js #

Docusaurus’s sidebar is determined in sidebars.js. There are two approaches. The first is autogeneration that follows the folder structure directly. The default template uses this approach.

sidebars.js — autogenerated 
export default {
  docsSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

With autogeneration, each doc’s sidebar_position sets the order, and a folder’s _category_.json sets the group name.

docs/guide/_category_.json 
{ "label": "Guide", "position": 2 }

Defining It Manually #

If you want full control over order and structure, write the sidebar yourself. List the doc ids and group them with category.

sidebars.js — manual definition 
export default {
  docsSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Guide',
      items: ['guide/getting-started', 'guide/configuration'],
    },
  ],
};

Have the top menu (navbar) point at the sidebar in docusaurus.config.js.

docusaurus.config.js — navbar 
navbar: {
  items: [
    { type: 'docSidebar', sidebarId: 'docsSidebar', label: 'Docs' },
  ],
}

Search — Not Built In #

Here Docusaurus differs from the earlier tools. Unlike Hugo Hextra or MkDocs Material, which include search by default, Docusaurus requires you to add search yourself. There are two options.

  • Algolia DocSearch — A hosted search officially supported by Docusaurus. Open-source projects can apply for free, and Algolia manages the index.
  • Local search plugin — A plugin like @easyops-cn/docusaurus-search-local builds the index at build time and works without any external service. For internal docs, including those in Korean, this is the more convenient route.

We’ll cover the concrete steps for adding it in #6, which deals with operations.

Wrapping Up #

In this post we set up the sidebar in sidebars.js, both automatically and manually, connected the top menu, and looked at the two search options. Aside from search requiring one extra step, the flow of structuring information is the same as with other tools.

In the next post we’ll cover writing content. From code blocks and Mermaid diagrams to admonitions that highlight cautions and warnings, we’ll lay out the elements that make docs easy to read.

X