MdBook – a command line tool to create books with Markdown

Typst is great, but really doesn't really serve the primary use case of mdbook which is building documentation websites or digital knowledge gardens that are accessible as a website.

If you are typesetting a research paper or writing a technical book for print publication typst is a great solution, but for a lot folks not having web support is an absolute dealbreaker.

Typst, with MathJax for math would be ideal! But I don't want to have to learn yet another syntax for math when LaTeX's math mode is burned into my brain.

It's been talked about here a bunch of times: https://hn.algolia.com/?q=Typst

Typst is amazing. You try it once and never want to go back to LaTeX again.

Does anyone use Typst for multi-page documentation website? This is the most common use-case of mdbook.

Pandoc[1] helps to convert markdown to pdf and epub

[1] https://pandoc.org/epub.html

I use Zola (https://github.com/getzola/zola) - pretty fast and I was able to customize a few things as well.

I’ve been running quarto [0] for a few months now and I’m happy with it. Posts are saved as .qmd, with a little bit of special front matter for formatting and tagging. `quarto render` converts the .qmd(s) according to a simple config file. [0] https://quarto.org/

> best system for Markdown-based static blogs

I use my Markdown editor[1] to produce my blog[2].

      keenwrite.bin -q -i "${FILE_MD}" -o "${FILE_HTML}" \
        --curl-quotes=true

Offers external variable sources, too; see [3] and [4].

[1]: https://keenwrite.com/

[2]: https://dave.autonoma.ca/blog/

[3]: https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd...

[4]: https://www.youtube.com/watch?v=CFCqe3A5dFg

It's `pandoc --from markdown-smart --to html5` for me.

VitePress and Docusaurus seem decent. I think VitePress might be more suited to blogging, but I admit I haven’t actually used or tested either.

https://docusaurus.io/

https://vitepress.dev/

I've been using Astro lately and loving it. It feels dead simple, has amazing defaults, and is easily extendable.

Opinions—Hugo or Jekyll for blogs. Yes, that Jekyll! Hugo gives you more rope to shoot yourself in the foot with.

MkDocs or Docusaurus for documentation. MdBook is not in the running, IMO, unless it’s radically improved since the last time I checked.

And here’s my hot take—most generators have a lot of the same design flaws. Routing is generally a mistake—you should instead design a system where every page has a URL that directly corresponds to the source file path, if feasible. Shortcodes are a mistake—you should use custom HTML tags. SSGs should have e.g. S3+Cloudfront as a core part of their design rather than just thinking of S3 as a place you put files when you’re done.

I'm satisfied with Hugo: https://gohugo.io/ It is very fast and has a lot of features. The syntax highlighting for code looks also very good.

I've been using Pelican [1] to generate my blog [2]. Here's how I set everything up: [3].

[1] https://getpelican.com/

[2] https://gurudas.dev/

[3] https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-d...

"The best" is, of course, Haunt, written in Guile. The following list has examples, and guides and so on:

  https://awesome.haunt.page/

A few hand-picked examples:

  https://jakob.space/blog/decompilation-by-hand.html
  https://guix.gnu.org/en/download/latest/
  https://www.gnu.org/software/guile/learn/

I know you asked for MD based system, but if you are willing to look beyond MD, I'd encourage to look into Antora[0] that's based on AsciiDoc. It's a full fledged documentation system that can span from single article to multiple books or product or technical documentation.

[0] https://antora.org/

I love hugo, it's a bit complex to get started with but extremely powerful. And the backward compatibility is very good, I started using that 4 years ago and aside of a handful of small issues which could be resolved in 5 min, my websites could be upgraded without any issue. This wasn't my experience with Jekyll.

There are 355 generators on this page, many of which support markdown: https://jamstack.org/generators/

If you want all the manual control like me, I suggest a build script that runs pandoc on .md files and injects HTML fragments into static templates.

There's nothing like Zine https://zine-ssg.io/. Alpha for now.

I've enjoyed building with SveltKit reading markdown files and processing them with it, into a static hosted site.

A few that come to mind:

Jekyll - written in Ruby

Hugo - written in Go

Zola - written in Rust

It's not static, but I've enjoyed GravCMS.

I use Jekyll. It’s pretty solid.

I’m happy with mkdocs.

[flagged]

Pandoc allows Markdown with fallback LaTeX which works incredibly well, imho. I suppose that is if you like both Markdown and LaTeX (along with the rest of its ecosystem).