Hacker News Reader

Why do you like Sphinx so much? Have you ever used MkDocs/Material for MkDocs? How do they compare?

At my last job I spent a fair amount of time on documentation, but I don't have a great understanding of what technical writers like/dislike, or what documentation systems are best.

View on HN

I like sphinx because I can make it do all the weird links between documents that I want. Markdown can't do that. I've never used MkDocs so I cannot comment.

I've used both extensively. (Material for) MkDocs is easy to set up and gives very good UX for users. Sphinx is hard to set up and provides better UX in some ways (internal links are on another level entirely), and worse UX in others (the themes are all worse than Material for MkDocs, every single one).

Reply on news.ycombinator.com