mdBook VS MkDocs

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

# Welcome to MkDocs For full documentation visit [mkdocs.org](https://www.mkdocs.org). ## Commands * `mkdocs new [dir-name]` - Create a new project. * `mkdocs serve` - Start the live-reloading docs server. * `mkdocs build` - Build the documentation site. * `mkdocs -h` - Print help message and exit. ## Project layout mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.

The documentation is built with MkDocs and hosted on GitHub Pages. You can browse the complete documentation at carpet.jerolba.com.

MkDocs

MkDocs is a static site generator designed specifically for project documentation and written in Python. It’s easy to set up, uses markdown for content, and features a number of themes, including the popular Material for MkDocs. MkDocs integrates well with Python-based workflows and CI/CD tools. It’s a great choice for Python developers and teams looking for simplicity and readability.

Because of my frustrations, I've released two example GitHub repositories for two popular static site generators: MkDocs and Sphinx. The goal with these repositories is to be focussed on a minimal project using the static site generator, that builds into a Read The Docs theme compatible website, and provide supporting tooling regarding formatting of the underlying formatting language. It also provides the tooling needed to deploy to GitHub Pages both from the command line and via GitHub Actions (both are powered by the ghp-import project).

The documentation of the CLI is provided via a GitHub page as part of the repository. We are using MkDocs to generate the content, but I think most of the tools in that area are well integrated with GitHub and GitHub Actions.

The original mkdocs uses a Python package for its installer, so you can just pip install mkdocs, mkdocs new ., and then mkdocs build to convert markdown files into HTML.

If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.