Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

MdBook – a command line tool to create books with Markdown

rust-lang.github.io

Post reply on HN
Print view View original

31–40 of 71 posts

Re: MdBook – a command line tool to create books with Markdown

#31

Post by dsr_ »

klodolph wrote: post #30
cyberax wrote: post #4

While we're on the topic of MD, what's the best system for Markdown-based static blogs these days? With good code highlighting, images, colors, etc.

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…

If you use S3+Cloudfront as a core part of your design then you limit your audience to people who want dependencies on S3+Cloudfront.

Re: MdBook – a command line tool to create books with Markdown

#32

Post by dsr_ »

jyap wrote: post #6
cyberax wrote: post #4

While we're on the topic of MD, what's the best system for Markdown-based static blogs these days? With good code highlighting, images, colors, etc.

A few that come to mind: Jekyll - written in Ruby Hugo - written in Go Zola - written in Rust

Pelican - written in Python

Re: MdBook – a command line tool to create books with Markdown

#33

Post by klodolph »

dsr_ wrote: post #31
klodolph wrote: post #30

Earlier quoted context omitted.

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…

If you use S3+Cloudfront as a core part of your design then you limit your audience to people who want dependencies on S3+Cloudfront.

That’s way off from what I meant, maybe I can clarify what I’m saying here.

You should consider the people who deploy to systems like S3+Cloudfront when designing your static site generator. Too many systems are just designed to be served from the filesystem and there are rough edges when you deploy to something like S3.

And “design for S3+Cloudfront” does not mean the same thing as “design it so that people without S3+Cloudfront are screwed”. That’s some kind of extrapolation.

The main relevant difference between e.g. S3 and a filesystem is that you can (and probably should) deploy pages to paths like /blog/hello/ rather than /blog/hello/index.html. There are other differences—it gets somewhat pervasive, unfortunately. There are hacks and workarounds but it would be nice if the SSGs were designed with cloud storage in mind as one of the core features, rather than an afterthought.

(It may seem funny that I keep saying “e.g.” but that’s because I’m not talking about S3 specifically, but speaking about a broader class of storage systems.)

Re: MdBook – a command line tool to create books with Markdown

#35

Post by TechDebtDevin »

klodolph wrote: post #30
cyberax wrote: post #4

While we're on the topic of MD, what's the best system for Markdown-based static blogs these days? With good code highlighting, images, colors, etc.

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…

I think OP is just referring to any SSG + CDN + S3, they probably just use AWS so its how they refer to it. I don't disagree.

On another note, I really like the way Cloudfront describes their "edge" offerings without having very annoying and obtuse usages of the word "edge": "Reduce latency by delivering data through 600+ globally dispersed Points of Presence (PoPs) with automated network mapping and intelligent routing."

This might be the first time I've seen anything on an AWS explained concisely and precisely /s (sorta).

Re: MdBook – a command line tool to create books with Markdown

#37

Post by bobbylarrybobby »

srid wrote: post #25
karteum wrote: post #17

I am happily experimenting with Typst right now ( https://typst.app/ ), which compiles much faster than LaTeX and with a syntax very similar to md, together with nice support for math, figures and advanced settings.

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

Given that Typst doesn't (yet) support html output, this seems impossible. I'd absolutely love to see it though.

Re: MdBook – a command line tool to create books with Markdown

#38

Post by arjvik »

karteum wrote: post #17

I am happily experimenting with Typst right now ( https://typst.app/ ), which compiles much faster than LaTeX and with a syntax very similar to md, together with nice support for math, figures and advanced settings.

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.

Re: MdBook – a command line tool to create books with Markdown

#39

Post by asicsp »

I use `mdbook` to provide free online versions of my ebooks (topics include regular expressions, Linux CLI tools and Vim): https://github.com/learnbyexample/scripting_course#ebooks

I chose `mdbook` over `pandoc` mainly because of themes and search provided by default.

Re: MdBook – a command line tool to create books with Markdown

#40

Post by asicsp »

cyberax wrote: post #4

While we're on the topic of MD, what's the best system for Markdown-based static blogs these days? With good code highlighting, images, colors, etc.

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