alt Hacker NewsI already think that markdown is barely ok for writing documentation, and the experience of plugins in mdBook is why I tell people not to use it (edit: it = mdBook). The base flavor of mdBook is minimalistic. Maybe that’s a good thing, that you’re given a minimalistic markdown as a starting point? But if it’s minimalistic, then it’s certainly missing some things that I’d want to use in the documentation I write, and the experience of using plugins is, well, not very good.
My current recommendations are MkDocs (material theme), Jekyll, and Docusaurus. Hugo gets a qualified recommendation, and I only recommend mdBook for people who are doing Rust stuff.
Replies
Markdown is devalued as a format because of the bizarre shortage of Markdown VIEWERS. You find Markdown documents in every open-source project, and you always wind up viewing them with all the embedded formatting characters. Why?
Why provide documentation in a format that is so poorly supported by READERS? Or, to respect the chicken-&-egg problem here: Why is there such a shortage of Markdown viewers?
Every time this comes up, respondents always cite this or that EDITOR that has Markdown "preview." NO. We're not editing the documentation; we're just reading it. So why do we have to load the document into an editor and then invoke a "preview" of it? Consider how nonsensical the term "preview" is in that case: What are we "previewing" its appearance in, given the dearth of Markdown readers?
What is missing from markdown? mdbook also uses in some parts the GH flavored one, so you can create notes [1] and similar. On top of that, you can add support for Mermaid.
Personally, I don't think you need more than that for 90% of the documentation, but I'm happy to hear more about your use case.
[1]: https://github.com/orgs/community/discussions/16925