Hacker News new | ask | show | jobs
by deathanatos 885 days ago
My org has used mdBook: https://rust-lang.github.io/mdBook/ (That link is itself a rendered mdBook, so that'll give you an idea of the feature set.)

(While it's definitely a Rust "thing", if you just have a set of .md files, all you need is a "SUMMARY.md" (which contains the ToC) and a small config file; i.e., you don't have to have any Rust code to use it, and it works fine without. We document a large, mostly non-Rust codebase with it.)
1 comments
webwanderings 885 days ago
This is pretty fast. Wow. Question for you. Does the search feature works out of the box, or does it need a plugin?
link
deathanatos 885 days ago
It works out of the box.

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.)

link