mdBook VS Docusaurus

I personally use mdbook (and another home-made system) to build my own sites/books. here you can see examples of public mdbooks in various languages. You can also see them grouped by language.

mdBook is a Rust-based tool to create Web-based books from vanilla Markdown files. Although it is quite minimalistic, you will bump into it quite often in the wild. Most notably, the Rust Book uses it. I see it quite often in the Nix ecosystem, too.

I have a local site I use as a knowledge base, journal and scratchpad. I recently migrated it from mdBook to Hugo, using the Hextra theme. The result was so good that I started questioning my use of Zola as my primary static site generator.

Nice work. Any plans to somehow integrate into mdbooks (https://rust-lang.github.io/mdBook/) ?

Or a general web user-interface?

mdBook - Create Books with Markdown in Rust

Biggest downside of this tool is inability to render PDF or ePub[1]. This is why we recently switched to Quarto[2]. Typst is also a good alternative, already mentioned in other comments.

[1] https://github.com/rust-lang/mdBook/issues/815

[2] https://quarto.org/

I think a good example is all of the wonderful documentation that's been created with mdBook.

Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that.

https://github.com/rust-lang/mdBook

Docusaurus is a powerful static site generator built by Meta and designed specifically for documentation websites. It’s React-based, which means you get a lot of flexibility in how you customize your site, and it comes with features that make API documentation much easier to manage:

We looked into a few different providers including GitBook, Docusaurus, Hashnode, Fern and Mintlify. There were various factors in the decision but the TLDR is that while we manage our SDKs with Fern, we chose Mintlify for docs as it had the best writing experience, supported custom React components, and was more affordable for hosting on a custom domain. Both Fern and Mintlify pull from the same single source of truth for the SDKs and docs site, respectively: Trophy’s OpenAPI spec.

Docusaurus is an open-source documentation site generator built by Meta, designed for creating optimized, fast, and customizable websites using React. It supports markdown files, versioning, internationalization (i18n), and integrates well with Git-based workflows. Its React architecture allows for deep customization and dynamic components. Docusaurus is ideal for developer-focused documentation with a need for flexibility and branding.

I think this is more a question of how you want to create and store your content and templates, like whether they exist as a bunch of Markdown files, database entries, a third-party API, etc. They're typically made to work in some sort of toolchain or ecosystem.

For example, if you're working in the React world, Next.js can actually output static HTML pages that work fine without JS... just use the pages router and a static export (https://nextjs.org/docs/pages/guides/static-exports). That still lets you use all the power of JS and expressiveness of React components, minus the interactivity, of course (if you don't want JS). But you could still pass in components and such. It's a bit like writing serverside includes in the PHP or Perl days. The benefit of using Next is its incredible popularity; probably whatever question you have, someone else has already asked and ten people have answered it. The downsides are its complexity and its frequent changes; answers from just a year or two ago are probably irrelevant to the current version, and there is a steep learning curve at first. But in SSG mode with the pages router, it's pretty straightforward, and the filesystem-based routing makes it very clear what the final directory structure would be.

For Markdown there's https://docusaurus.io/

For this challenge, I've built a simple static website based on Docusaurus for tutorials and blog posts. As I'm not too seasoned with Frontend development, I only made small changes to the template, and added some very simple blog posts and tutorials there.

Dumi. A static site generator specifically designed for component library development. Look at it as something between Storybook and Docusaurus inside the Umi world (but much better integrated between each other, presumably).

Static site generators like Docusaurus offer flexibility for teams comfortable with Markdown and Git workflows

I really like the idea and what you’re building here. That said, I’d argue the documentation website is the face of any open-source project. Reinventing the wheel rarely ends well — the current docs are hard to navigate and read.

Just use an off-the-shelf solution for docs, like Docusaurus, for example:

https://github.com/facebook/docusaurus

Static websites are so good that they even have their own three-letter abbreviation: SSG (Static Site Generation). And of course, there are plenty of frameworks that generate them for you, no need in manual labour: Next.js supports SSG, Gatsby is still pretty popular, lots of people love Docusaurus, Astro promises the best performance, and probably many more.