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.