mdBook

mdBook is an easy way to create modern online books using Markdown. The program itself is written in Rust, and is used for the Rust Book and many project’s documentation. It has a really nice search feature, a minimal interface, and is easy to use. For courses that are a part of the Quaternion Institute, I recently decided to use mdBook.

Usage

If you don’t have Rust installed, get it from Rustup, then run cargo install mdbook. Create a new book with mdbook init book_name, then edit src/SUMMARY.md and describe your books structure in an outline as shown in the user guide. Run mdbook serve or mdbook build and it will create all of the files that don’t exist that are linked to in the directory, and then you can start writing.

Notes

I was using Vimwiki for notes, but I have decided to switch (no effort required, really) to mdBook. Many people prefer Vimwiki’s Markdown syntax (it’s objectively better) instead of its own Vimwiki syntax, but Vimwiki can only generate webpages from its own syntax. mdBook is a good solution for this.

Preprocessors

mdbook-katex

mdBook supports MathJax out of the box, which is inferior to KaTeX for rendering math on webpages. mdbook-katex is a preprocessor that uses KaTeX to render all of your math to SVG at build-time. If you want to have math in your HTML-based notes, I assure you this is the best way.

mdbook-linkcheck

I contribute to documentation on GitHub a lot because broken links bother me way more than they should. Save your sanity (or atleast mine): mdbook-linkcheck.

Others

There is an open GitHub issue to add a list of preprocessors to the user guide. Until then, there is a list of them in the issue to which I have added many.

My Setup

Between the two, I have a nice way to write Markdown: Neovim + Goyo.vim + Vimwiki, and a nice way to read it: Firefox + mdBook. I use Goyo.vim to hide Neovim’s interface to eliminate distractions, and Vimwiki is pretty much installed only for the link navigation feature now. Hover over a Markdown link such as [link](file2.md) and press enter, and Vimwiki switches you over to file2.md.

Conclusion

If you want searchable Markdown-formatted notes, try mdBook. It’s simple and does everything I expect it to. There is a multilingual option in my book.toml which makes me hope that support for multilingual books will be added soon.