MkDocs
Ranked 9 of 10 static site generators by recommenders
People use MkDocs to turn documentation into a static HTML site, often rebuilt automatically on commit. Critics find setup and YAML configuration fiddly.
People use MkDocs to turn documentation into a static HTML site, often rebuilt automatically on commit. Critics find setup and YAML configuration fiddly.
14 people gave an opinion
- recommend it
- 7
- criticize it
- 7
- approval share
- 50%
Recommended in 6 of 13 months
- November 2025: not recommended
- December 2025: recommended
- January 2026: not recommended
- February 2026: not recommended
- March 2026: recommended
- April 2026: recommended
- May 2026: recommended
- June 2026: not recommended
- July 2026: not recommended
- August 2026: not recommended
- September 2026: recommended
- October 2026: recommended
- November 2026: not recommended (month in progress)
Why it doesn’t carry the badge
- 7 people recommend itNeeds 10 or more, not met.
- 1 recommender for every criticNeeds 2 to 1 or better, not met.
- Recommended in 6 of 13 monthsNeeds 4 or more, met.
The same three rules apply to every product, and the badge can’t be bought. How the badge works
What people say about it
The reasons people give, with the number of comments that give each one. Open a reason to read what they said.
Why people recommend it
Each mark is one comment
Works well for documentation sites
“I found mkdocs works pretty well and integrated with a github job that updates the docs when I commit changes to my main branch.”
Comment from 11 Oct 2026 in “I paid people to try and follow my README” “it's awesome and I've used it more than once”
Comment from 6 May 2026 in “Our Continuation of MkDocs” Static HTML publishing for docs
“Later, if you want to publish the files as HTML, you can use MkDocs.”
Comment from 12 Apr 2026 in “A practical guide for setting up Zettelkasten method in Obsidian” “We've been doing this with simple mkdocs for ages.”
Comment from 29 Mar 2026 in “Lat.md: Agent Lattice: a knowledge graph for your codebase, written in Markdown” “Static sites all the way (hugo, jekyll, mkdocs!)”
Comment from 8 Sep 2026 in “We have a year to fix security everywhere” Used repeatedly over many years
“We've been doing this with simple mkdocs for ages.”
Comment from 29 Mar 2026 in “Lat.md: Agent Lattice: a knowledge graph for your codebase, written in Markdown” “it's awesome and I've used it more than once”
Comment from 6 May 2026 in “Our Continuation of MkDocs”
What people warn about
Each mark is one comment
Setup and YAML indentation trouble
“we got a lot of issues with users having trouble just getting the indentation of YAML right”
Comment from 10 Nov 2025 in “Zensical – A modern static site generator built by the Material for MkDocs team” “mkdocs is not simple to setup”
Comment from 9 Nov 2025 in “Zensical – A modern static site generator built by the Material for MkDocs team” Author conduct and package hijacking
“the comments the MkDocs author is making about perceived gender grievances feel so unhinged”
Comment from 25 Mar 2026 in “I Forked Httpx” “I still think that hijacking the mkdocs package was the wrong way to go though.”
Comment from 25 Mar 2026 in “I Forked Httpx” “MkDocs became an absolute shit-show that fucked everyone over”
Comment from 28 Aug 2026 in “Migrating to HTTPX2” Dated; no parallel builds
“mkdocs still uses "web fonts" for icons. This hack was required for compatibility with Internet Explorer, but is just cargo-culting these days.”
Comment from 11 Oct 2026 in “I paid people to try and follow my README” “mkdocs has no parallization and brings nothing to the table compared to sphinx since its inception”
Comment from 6 May 2026 in “Our Continuation of MkDocs”
Other static site generators people recommend
The four most recommended other static site generators, with the same counts for each, so you can compare like for like. The tick on each bar marks the 2 to 1 line the badge needs.
| Product | Recommend | Criticize | Approval | Months | Owned | Badge |
|---|---|---|---|---|---|---|
| Astro | 174 | 36 | 83% | 13 | 2 yrs9 owners | Approved |
| Hugo static site generator | 85 | 40 | 68% | 12 | 3.5 yrs9 owners | Approved |
| Jekyll | 29 | 14 | 67% | 7 | 10 yrs5 owners | Approved |
| Eleventy | 22 | 3 | 88% | 6 | 3 yrs3 owners | Approved |
| MkDocsThis page | 7 | 7 | 50% | 6 | — | — |
What people said
14 of the 15 comments that mention it, newest first. Each links to the original comment.
“mkdocs still uses "web fonts" for icons. This hack was required for compatibility with Internet Explorer, but is just cargo-culting these days.”
“I found mkdocs works pretty well and integrated with a github job that updates the docs when I commit changes to my main branch.”
“Static sites all the way (hugo, jekyll, mkdocs!)”
“MkDocs became an absolute shit-show that fucked everyone over”
“mkdocs has no parallization and brings nothing to the table compared to sphinx since its inception”
“it's awesome and I've used it more than once”
“Later, if you want to publish the files as HTML, you can use MkDocs.”
“We've been doing this with simple mkdocs for ages.”
“the comments the MkDocs author is making about perceived gender grievances feel so unhinged”
“I still think that hijacking the mkdocs package was the wrong way to go though.”
“using mkdocs which comes close to what I would want”
“we got a lot of issues with users having trouble just getting the indentation of YAML right”
“mkdocs is not simple to setup”
“We ran against walls trying to realize our ideas with MkDocs' APIs”
Counts come from 1,795,640 Hacker News comments, November 2025 to November 2026. How we count. Report a mistake.