Hacker News Reader

Comment by paholg | Hacker News Reader

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

View on HN

Thanks, but this does not seem to involve hosting? What I'm saying is, static site generation is no problem at all, because even without all the choices for frameworks, pretty much everyone has to speak at least one templating language and read/write both markdown and rst anyway. But it's surprising that writing your project docs and rolling your own static-site generator is faster than figuring out github-pages and/or readthedocs hosting from scratch.

For hosting static sites, I actually like AWS amplify, and integrating it with github seems currently easier and certainly more flexible than trying to use github pages. But I don't really want the hassle of a custom domain or a subdir on existing inappropriate domains for every new project I start.

This isn't about being cheap either BTW, I think it's important that self-hosting should NOT be the best way to get a friction-free setup for small-to-medium sized project docs. There's a major benefit just to the recognizable domains for github-pages / readthedocs, which is that I know I'm about to look at some kind of technical project documentation that is most likely a labor of love, rather than marketing fluff or a "sign up for the preview here!" bait and switch.

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...

Reply on news.ycombinator.com