MdBook – A command line tool to create books with Markdown

What zealotry? Rust isn't mentioned until the last two points of eight:

mdBook is a command line tool to create books with Markdown. It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.

- Lightweight Markdown syntax helps you focus more on your content - Integrated search support - Color syntax highlighting for code blocks for many different languages - Theme files allow customizing the formatting of the output - Preprocessors can provide extensions for custom syntax and modifying content - Backends can render the output to multiple formats - Written in Rust for speed, safety, and simplicity - Automated testing of Rust code samples

It mentions Rust because it's written in Rust and used by the Rust project.

In other words, the project wouldn't exist without Rust but

Embarrisngly, I'm using both for docs at work (they were both projects I started).

Mkdocs is more flexible, has more themes, better ecosystem. Mdbook has better defaults, easier deployment, is more standard across rust projects

I used to use gitbook to generate til.secretGeek.net but it got slower and slower over time, would take 45 mins to build the site… and then the parts I was using were either deprecated or made “premium” - something happened. The “enshittification” set in, basically. If there’s some nice free thing you use that’s too good to be true… wait a few years it will go to muck.

I bit the bullet and wrote my own very minimal static site generator in .net, so the site builds in a few seconds again. Note that I’m not spruiking it for others to use… because if it became popular, no doubt I’d end up enshittifying it too.

I’ve used both, I recommend MkDocs over MdBook for most people. MdBook is simpler and easier to get started with, MkDocs has more features, more plugins, more themes. Both MkDocs and MdBook are easy to use. IMO, MdBook is a little too simple.

Recommend using the material design theme for MkDocs as a starting point. If you are working on a Rust project, use MdBook instead. If you have lots of docs / multiple projects / multiple versions, use Antora. If you want cooler landing pages, use Jekyll.

Wow, what is up with the material mkdocs theme (https://squidfunk.github.io/mkdocs-material/)? That's an extremely spiffy landing page, especially given that it's for a theme designed for a totally separate piece of software.