4 ms·
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. MdBoo
by klodolph 2y ago
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.
- dsr_ 2y agoIf you use S3+Cloudfront as a core part of your design then you limit your audience to people who want dependencies on S3+Cloudfront.
- klodolph 2y agoThat’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.)
- TechDebtDevin 2y agoI 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).
- rapnie 2y agoRegarding MkDocs there's the great Material for MkDocs [0] for documentation. [0] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/
- klodolph 2y agoDefinitely. I think people using MkDocs should use Material as their first choice.