shouldiuse.io

VERDICT

Should I use MkDocs?

Project documentation with Markdown - mkdocs.org

Depends. Adopt it if your team lives in Markdown and Git and wants free docs-as-code. Skip it if you need hosted, supported, customer-facing documentation or long-term theme support.

Confidence

Medium. Based on ~40 public sources; some review snippets were truncated.

Ratings

  • Value for money
  • Ease of use
  • Feature depth
  • Support quality
  • Security posture

Pricing

Free, open source

MkDocs core

ModelNot disclosed
Monthly feesNot disclosed
HardwareNot disclosed
Free tierYes
Material for MkDocs InsidersSponsorship-based, varies

Best for

  • Developer and DevOps teams
  • Docs-as-code Markdown workflows in Git
  • Open-source project documentation
  • CI/CD-published internal docs

Not for

  • Non-technical writers wanting WYSIWYG editing
  • Customer-facing help centers needing search and analytics
  • Teams requiring vendor SLAs and paid support
  • Anyone betting on long-term theme maintenance

Gotchas - check before you buy

high

Material theme's security policy ends support after May 5, 2027

medium

Official site has no security page; you vet patches yourself

medium

Free means you own CI builds, hosting, and maintenance labor

low

Material Insiders is sponsorship-priced; changes announced via GitHub issue

Pros and cons

Pros

  • Completely free and open source
  • Fast, simple Markdown-to-site generation
  • Strong plugin and theme ecosystem
  • Fits Git-based review workflows (GitLab MRs)
  • Widely used, including Microsoft engineering playbooks

Cons

  • Public maintainer-concern discussions; 'slow collapse' worries
  • Material for MkDocs theme now in maintenance mode
  • Static output only: no built-in hosting, auth, or analytics
  • No vendor support; dependent on volunteer maintainers
  • Security issues concentrated in plugins and themes

Sources & method

Analyzed 9/24/2026 - 9 sources - Core and ecosystem have real CVEs; no official security page; flagship theme support winding down.

official x1review x4security x2news x2
  • CVE-2026-25153: Backstage TechDocs MkDocs RCE, Remote code execution in MkDocs pipeline used by Backstage TechDocs.
  • CVE-2026-73295: Material for MkDocs XSS, DOM-based cross-site scripting flaw in Material for MkDocs.
  • CVE-2025-59940: include-markdown plugin input flaw, Input vulnerability in mkdocs-include-markdown-plugin.
  • CVE-2021-40978: path traversal in MkDocs, Verified path traversal issue in core MkDocs.

Key stats

  • Value for money: 5/5

    Rating

  • Free, open source

    Starting price

  • 9

    Sources

  • Analyzed

  • Value for money: 5/5. Completely free, no license costs
  • Ease of use: 4/5. G2 calls it fast and simple
  • Feature depth: 3/5. Static output only; plugins required for extras
  • Support quality: 2/5. Community-driven; public maintainer concerns
  • Security posture: 2/5. Multiple ecosystem CVEs; no security page
  • $0 Price open source, MIT-style
  • Yes Free tier entire core product is free
  • 472 companies Adoption tracked by TheirStack

Pricing

MkDocs core

Free, open source

  • Full static site generator
  • All Markdown docs features

Material for MkDocs Insiders

Sponsorship-based, varies

  • Premium theme features
  • Price changes announced on GitHub

Security

Core and ecosystem have real CVEs; no official security page; flagship theme support winding down.

  • CVE-2026-25153: Backstage TechDocs MkDocs RCERemote code execution in MkDocs pipeline used by Backstage TechDocs.⁶
  • CVE-2026-73295: Material for MkDocs XSSDOM-based cross-site scripting flaw in Material for MkDocs.
  • CVE-2025-59940: include-markdown plugin input flawInput vulnerability in mkdocs-include-markdown-plugin.
  • CVE-2021-40978: path traversal in MkDocsVerified path traversal issue in core MkDocs.

What users say

Developers praise MkDocs as fast and simple for Markdown docs, while recent community threads question its long-term maintenance.

“We've got MKDocs set up”
Reddit, r/technicalwriting
“I've just deployed an instance of MKDocs for my company's”
Reddit, r/technicalwriting
“MkDocs is a fast, simple”
G2 reviews

Companies that use it

  • Siemens⁸
  • Microsoft
  • NHS Digital
Full analysis

Based on ~40 public sources; some review snippets were truncated.

Free, simple Markdown docs generator. Great for dev teams; risky now — top theme in maintenance mode, no vendor support.

Methodology

Based on ~40 public sources; some review snippets were truncated.

Sources

  1. MkDocs official sitemkdocs.org
    official
  2. MkDocs G2 reviewsg2.com
    review
  3. The Slow Collapse of MkDocsreddit.com
    review
  4. Concerns about maintainership of MkDocsgithub.com
    review
  5. Material for MkDocs: Honest 2026 Review (Maintenance Mode)docsio.co
    review
  6. CVE-2026-25153: Backstage TechDocs MkDocs RCEmiggo.io
    security
  7. MkDocs security pagemkdocs.org
    security
  8. Visual review of MkDocs sites in GitLab MRs — Siemensblog.siemens.com
    news
  9. Companies that use MkDocs (472)theirstack.com
    news

Rate this review

Anonymous. You can change your vote.

Loading votes…

Comments

One queue. No nested comments. Give a display name first. Limit: 200 words per comment and 7 comments per day. You can edit or delete yours.

Save a name to write a comment.

0 / 200 words

No comments yet.