Build a Manual with MkDocs #2: nav and Search — Shaping the Information Structure of Your Docs

Framework MkDocs Documentation Static Site
3 min read

In #1 we served our first doc with MkDocs Material. When you have only a page or two, structure isn’t a problem. The problem shows up when the docs grow to dozens of pages. A manual must always let the reader know “where in the whole the item I’m looking at sits.” What does that job is the sidebar and search. In MkDocs, the sidebar is called the nav.

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

  • #1: From Install to Your First Doc
  • #2: nav and Search — Shaping the Information Structure of Your Docs ← this post
  • #3: Writing Content — Code Blocks, Mermaid, and Admonitions
  • #4: Deploy on Cloudflare Pages and Connect a Domain
  • #5: Multilingual Docs and Versioning
  • #6: Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover designing the nav directly, turning on Material’s navigation features, and refining search.

You Write the nav Directly in mkdocs.yml #

This is where the character of MkDocs becomes clear. Some tools build the sidebar automatically from the folder structure, but MkDocs has you write it directly in the nav of mkdocs.yml. It takes a bit more work, but in exchange you have complete control over the order and labels.

mkdocs.yml — nav 
site_name: Product Manual
theme:
  name: material

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Configuration: configuration.md

The left-hand label is the name shown in the sidebar, and the right-hand side is the file path under docs. Files not listed in nav don’t appear in the sidebar, so it’s also easy to keep drafts hidden.

Grouping into Sections #

When items grow, you need to group them. Nesting the nav turns it directly into sections in the sidebar.

mkdocs.yml — nested sections 
nav:
  - Home: index.md
  - Guide:
      - Getting Started: guide/getting-started.md
      - Configuration: guide/configuration.md
  - Advanced:
      - Plugins: advanced/plugins.md

Guide and Advanced become expandable groups, with the pages nested beneath them. No matter which folder you put a file in, the sidebar structure is determined by nav.

Tuning the Presentation — Theme Features #

Material turns on navigation behaviors with theme.features. Pick the ones that fit the size of your docs.

mkdocs.yml — navigation features 
theme:
  name: material
  features:
    - navigation.sections   # Display sections grouped in an expanded state
    - navigation.top        # Back-to-top button
    - toc.integrate         # Integrate the right-hand table of contents into the sidebar
    - search.suggest        # Search autocomplete

Adding navigation.tabs lifts the top-level sections up into tabs at the top, while navigation.expand expands every section from the start. Tabs fit shallow docs well, and expansion fits deep ones.

Search #

The good news is you don’t need to bolt on search separately. Material turns on built-in search by default, builds the index at build time, and ships it as static files alongside the deployment. No server required.

The one thing to tweak is Korean. The default tokenization splits on whitespace, but Korean attaches particles to words, so searches may match less often than expected. Adjusting the separator of the search plugin breaks words up more finely.

mkdocs.yml — search (Korean) 
plugins:
  - search:
      separator: '[\s\-]+'

Wrapping Up #

In this post we designed the sidebar directly with nav, turned on Material’s navigation features, and tuned search for Korean. Now, even as the docs grow, readers can gauge their position from the sidebar and jump straight to what they need via search.

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

X