# MkDocs

7 Hacker News commenters recommended MkDocs and 7 criticized it, November 2025 to November 2026. It was recommended in 6 of 13 months.

**Verdict:** People use MkDocs to turn documentation into a static HTML site, often rebuilt automatically on commit. Critics find setup and YAML configuration fiddly.

## Why people recommend it

- Works well for documentation sites (2 comments): "I found mkdocs works pretty well and integrated with a github job that updates the docs when I commit changes to my main branch." ([source](https://news.ycombinator.com/item?id=50043177)) "it's awesome and I've used it more than once" ([source](https://news.ycombinator.com/item?id=48039178))
- Static HTML publishing for docs (3 comments): "Later, if you want to publish the files as HTML, you can use MkDocs." ([source](https://news.ycombinator.com/item?id=47735054)) "We've been doing this with simple mkdocs for ages." ([source](https://news.ycombinator.com/item?id=47563551)) "Static sites all the way (hugo, jekyll, mkdocs!)" ([source](https://news.ycombinator.com/item?id=49606198))
- Used repeatedly over many years (2 comments): "We've been doing this with simple mkdocs for ages." ([source](https://news.ycombinator.com/item?id=47563551)) "it's awesome and I've used it more than once" ([source](https://news.ycombinator.com/item?id=48039178))

## What people warn about

- Setup and YAML indentation trouble (2 comments): "we got a lot of issues with users having trouble just getting the indentation of YAML right" ([source](https://news.ycombinator.com/item?id=45873956)) "mkdocs is not simple to setup" ([source](https://news.ycombinator.com/item?id=45868400))
- Author conduct and package hijacking (3 comments): "the comments the MkDocs author is making about perceived gender grievances feel so unhinged" ([source](https://news.ycombinator.com/item?id=47516595)) "I still think that hijacking the mkdocs package was the wrong way to go though." ([source](https://news.ycombinator.com/item?id=47514986)) "MkDocs became an absolute shit-show that fucked everyone over" ([source](https://news.ycombinator.com/item?id=49478686))
- Dated; no parallel builds (2 comments): "mkdocs still uses "web fonts" for icons. This hack was required for compatibility with Internet Explorer, but is just cargo-culting these days." ([source](https://news.ycombinator.com/item?id=50043222)) "mkdocs has no parallization and brings nothing to the table compared to sphinx since its inception" ([source](https://news.ycombinator.com/item?id=48040434))

## Alternatives hackers recommend

- [Astro](https://hackerapproved.com/p/astro.md): 174 recommend
- [Hugo static site generator](https://hackerapproved.com/p/hugo.md): 85 recommend
- [Jekyll](https://hackerapproved.com/p/jekyll.md): 29 recommend
- [Eleventy](https://hackerapproved.com/p/eleventy.md): 22 recommend
- [Zensical](https://hackerapproved.com/p/zensical.md): 17 recommend

## Cite as

Hacker Approved, "MkDocs", https://hackerapproved.com/p/mkdocs/ (counts from 1,795,640 Hacker News comments, November 2025 to November 2026).