How to search a documentation folder

This guide shows how to search the text files of a folder — Markdown, AsciiDoc, plain text — by hand with /docs, or by letting the model search with its search_docs tool before it answers. The search ranks passages with BM25 and loads no model.

Search by hand

Turn the command on and name the folders, in the agent's YAML:

docSearch:
  searchDocs: true
  dirs: [docs]
  extensions: [.md]

Start mm — the terminal, the window (mm -tui) or an editor — and type the words you are looking for:

/docs liststate

🔎 5 passage(s) for "liststate" — 10 file(s) in docs

── docs/04-lists.md:5 · Lists and selection › Keep the selection with ListState
## Keep the selection with ListState

`ListState` remembers which item is selected and how far the list is scrolled. …

Each passage starts with its link, path:line, which an editor opens and read_file reads. The model is not called and the conversation is not changed.

Let the model search

Declare the tool:

docSearch:
  autoSearchDocs: true
  dirs: [docs]
  extensions: [.md]

Tell the model, in its system prompt, when to call it and how to quote what it finds. What worked on a 4B model:

system: |
  For any question the documentation may cover, call search_docs first, with English
  words — type and function names work best. Answer from the passages it returns,
  and end with the link of the passage you used (path:line).

The two switches are independent: searchDocs alone gives you the command and the model no tool; autoSearchDocs alone the reverse.

Variants

Several folders, several formats. dirs: [docs, guides, /shared/handbook], extensions: [.md, .adoc, .txt]. Only the listed extensions are read.
Over ACP. Relative folders are resolved against the session's cwd: the project the editor opened.
Large files. Files above maxFileSize (default 1MB) are skipped; raise it, or split the file.
Questions in another language. The search matches words, not meanings. Documentation in English searched with French words finds nothing — ask the model to search with the documentation's words (see the prompt above), which a small model did reliably in demos/docs-search/.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


# How to search a documentation folder

This guide shows how to search the text files of a folder — Markdown, AsciiDoc, plain text — by hand with `/docs`, or by letting the model search with its `search_docs` tool before it answers. The search ranks passages with BM25 and loads no model.

## Search by hand

1. Turn the command on and name the folders, in the agent's YAML:

   ```yaml
   docSearch:
     searchDocs: true
     dirs: [docs]
     extensions: [.md]
   ```

2. Start mm — the terminal, the window (`mm -tui`) or an editor — and type the words you are looking for:

   ```text
   /docs liststate
   ```

   ```text
   🔎 5 passage(s) for "liststate" — 10 file(s) in docs

   ── docs/04-lists.md:5 · Lists and selection › Keep the selection with ListState
   ## Keep the selection with ListState

   `ListState` remembers which item is selected and how far the list is scrolled. …
   ```

Each passage starts with its link, `path:line`, which an editor opens and `read_file` reads. The model is not called and the conversation is not changed.

## Let the model search

1. Declare the tool:

   ```yaml
   docSearch:
     autoSearchDocs: true
     dirs: [docs]
     extensions: [.md]
   ```

2. Tell the model, in its `system` prompt, when to call it and how to quote what it finds. What worked on a 4B model:

   ```yaml
   system: |
     For any question the documentation may cover, call search_docs first, with English
     words — type and function names work best. Answer from the passages it returns,
     and end with the link of the passage you used (path:line).
   ```

The two switches are independent: `searchDocs` alone gives you the command and the model no tool; `autoSearchDocs` alone the reverse.

## Variants

- **Several folders, several formats.** `dirs: [docs, guides, /shared/handbook]`, `extensions: [.md, .adoc, .txt]`. Only the listed extensions are read.
- **Over ACP.** Relative folders are resolved against the session's `cwd`: the project the editor opened.
- **Large files.** Files above `maxFileSize` (default `1MB`) are skipped; raise it, or split the file.
- **Questions in another language.** The search matches words, not meanings. Documentation in English searched with French words finds nothing — ask the model to search with the documentation's words (see the prompt above), which a small model did reliably in `demos/docs-search/`.

## See also

- [Configuration reference](../reference/configuration.md#docsearch-keys) — `docSearch`
- [Slash commands reference](../reference/slash-commands.md) — `/docs`
- [Tools reference](../reference/tools.md#search_docs) — `search_docs`
- [Why the documentation search works this way](../explanation/document-search.md)
- `demos/docs-search/` — a measured demo: an assistant answering from nine Ratatui tutorials