I’ve done this thing a few times where I have a nice layout of about 5-10 pages of markdown docs, themselves rendered from more dynamic jinja templates, and feel that life is pretty good. Looks great, got a real build process for auto docs, but too big for a monolithic GitHub readme. Now the pain starts.
GitHub’s own docs for project pages don’t work. Do I need a .nojekyl file, are gh-pages branches still required? Is there a config error in the repo or did changes just not prop? I guess I’ll try actions. Fast forward a few hours and this is getting unreasonable, haven’t looked at read the docs in a while, let’s see if that works. Ok it’s being weird and wants sphinx maybe, let’s get sphinx to work with markdown, ok cool. The build works but the page width is broken after deployment even though I can’t reproduce on my machine so it must be the ads injection on the community tier.
I know all this is working fine for lots of projects and have done it myself in the past. It works after it’s working. But it’s all so unbelievably fiddly. Bottom line, Markdown vs Rst isn’t even a choice/pain point on my radar, it’s more down to finding that good fit for medium sized docs projects / static hosting.
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.
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.
GitHub’s own docs for project pages don’t work. Do I need a .nojekyl file, are gh-pages branches still required? Is there a config error in the repo or did changes just not prop? I guess I’ll try actions. Fast forward a few hours and this is getting unreasonable, haven’t looked at read the docs in a while, let’s see if that works. Ok it’s being weird and wants sphinx maybe, let’s get sphinx to work with markdown, ok cool. The build works but the page width is broken after deployment even though I can’t reproduce on my machine so it must be the ads injection on the community tier.
I know all this is working fine for lots of projects and have done it myself in the past. It works after it’s working. But it’s all so unbelievably fiddly. Bottom line, Markdown vs Rst isn’t even a choice/pain point on my radar, it’s more down to finding that good fit for medium sized docs projects / static hosting.