It's pretty basic: mdBook just emits a JSON file containing the entire search index. The rendered book's JS then fetches that index, and uses it to implement the search client-side. (So that the whole book — search index included — can be served statically.)
It usually finds what I'm looking for pretty easily, as long as I pick a good search term. It isn't the best search, though, and sometimes I'll just revert to `rg` in a CLI if it's in the way.
The things I think people in our org didn't like: some people really really want a WYSIWYG editor, some people don't want to have to deal with making a commit to update docs¹, some people didn't like that the ToC enforced a hierarchy (and wanted a more Wiki style thing²).
(¹I'm in the camp that docs should be reviewed through normal processes, though … I've seen a lot of instances otherwise of incorrect docs getting through, and/or just bad/nonsensical docs getting written. Our org's code review policy at the time most of the docs were written was "you should get a review, but a bot will auto-stamp it if you want to opt-out and then it's just on you", but nowadays we require review, but I don't feel like the reviews are rigorous.)
(²to me a ToC is a wiki superset: if you want wiki behavior … just create a single level in the ToC, and all docs are at the same level. Alphabetize them if you don't want to think about the order. We call this section "Misc" in our ToC, but we do break some other parts out into more full-fledged sections. mdBook enforces that docs must appear in the ToC, which I think is a good thing for discoverability.)
deathanatos|2 years ago
It's pretty basic: mdBook just emits a JSON file containing the entire search index. The rendered book's JS then fetches that index, and uses it to implement the search client-side. (So that the whole book — search index included — can be served statically.)
It usually finds what I'm looking for pretty easily, as long as I pick a good search term. It isn't the best search, though, and sometimes I'll just revert to `rg` in a CLI if it's in the way.
The things I think people in our org didn't like: some people really really want a WYSIWYG editor, some people don't want to have to deal with making a commit to update docs¹, some people didn't like that the ToC enforced a hierarchy (and wanted a more Wiki style thing²).
(¹I'm in the camp that docs should be reviewed through normal processes, though … I've seen a lot of instances otherwise of incorrect docs getting through, and/or just bad/nonsensical docs getting written. Our org's code review policy at the time most of the docs were written was "you should get a review, but a bot will auto-stamp it if you want to opt-out and then it's just on you", but nowadays we require review, but I don't feel like the reviews are rigorous.)
(²to me a ToC is a wiki superset: if you want wiki behavior … just create a single level in the ToC, and all docs are at the same level. Alphabetize them if you don't want to think about the order. We call this section "Misc" in our ToC, but we do break some other parts out into more full-fledged sections. mdBook enforces that docs must appear in the ToC, which I think is a good thing for discoverability.)