mdBook

Biggest problem of mdBook is the lack of the good PDF and ePub export[1]. This is why Quarto[2] (based on pandoc) is a better choice if you need both online and offline rendered documentation/text. And Typst (or LaTeX for more conservative folks) for the offline documentation/articles/books. [1] https://github.com/rust-lang/mdBook/issues/815 [2] https://quarto.org/

I really like this reactive guide style interface, which maybe could be quite a good project idea like mdBook[1] but also you to insert quizzes/examples alongside static notes [1]: https://github.com/rust-lang/mdBook

I'd rather use Markdown for writing and even user submitted content whenever possible instead of gag HTML or some other overcomplicated markup language. Sure, there's various different flavors of Markdown, but on average it's better than overcomplicated attribute ridden XML or even XSS prone HTML (where nobody even knows what section is and everything ends up being a div). Just give me a good enough baseline, that's it. Markdown is close enough to that for now. I don't need that much semantic meaning in the text. Something like mdbook (https://github.com/rust-lang/mdBook) is more than enough for my needs, compared to shipping docs in once again, gag DOCX files and PDFs. Good that there are solutions for more advanced use cases, though, but be careful with that complexity where you don't need it.

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, someon

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/

quite sure that is my limit but what is the difference between this and other "md compiler" projects (or ssr) like <https://github.com/rust-lang/mdBook>? Anyway this seems to work very well, so congrats!

That's what I meant by instructions on automated deployments. MdBook generates HTML, so you don't need anything fancy to host it. This example shows a fairly short GitHub action to deploy to GitHub pages: https://github.com/rust-lang/mdBook/wiki/Automated-Deploymen...

Have you looked into mdBook? I haven't used it myself, but I've enjoyed the documentation of many projects that do and it seems really nice once you get past the point where a single readme file works well. They also have some nice instructions on automated deployments. https://github.com/rust-lang/mdBook

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

I use pandoc to convert markdown to pdf+epub (https://learnbyexample.github.io/customizing-pandoc/). For web version, I use mdbook (https://github.com/rust-lang/mdBook) mainly because it comes with user choosable themes and search by default. However, if I had to start from scratch, I'd probably look at Quarto (https://quarto.org/) or Mau (https://project-mau.github.io/index.html)

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

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

I use it to generate PDF/EPUB versions from GitHub style markdown for my ebooks. The default output was good enough, but I wanted to customize a few things [0]. I didn't know LaTeX, but I was able to use solutions from stackoverflow sites. Later I found that some users had created templates I could've borrowed. I use mdBook [1] for web versions though. I found the default setup much easier to use. And it came with themes (light/dark/etc) that readers can choose. [0] https://learnbyexample.github.io/customizing-pandoc/ [1] https://github.com/rust-lang/mdBook

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

Author of the book here — yes, I used Mdbook (https://github.com/rust-lang/mdBook), and the links strangely end with `.html. as you correctly updated. Initially, I wanted to change it but left it as it was.