{"slug": "material-for-mkdocs", "name": "Material for MkDocs", "category": "notes", "category_name": "Notes and knowledge", "description": "", "recommenders": 3, "commenters": 7, "warners": 0, "score": 3.396, "rising": -0.98, "first": "2025-11-09", "latest": "2026-03-25", "why": "I'm using mkdocs+material for one site (and it's great)", "why_is_quote": true, "has_verdict": false, "sentiment": {"recommend": 2, "neutral": 4, "compare": 1, "warn": 0}, "spark": [2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], "listed": true, "loved": [], "caveat": "", "short_quote": "I'm using mkdocs+material for one site (and it's great)", "kind": "", "icon": false, "domain": null, "github_repo": null, "official_url": "https://squidfunk.github.io/mkdocs-material/", "pricing": "", "aliases": ["Material for MkDocs"], "verdict": null, "praise": [{"label": "", "summary": "", "quotes": [{"id": 733982273, "item_id": 45873892, "url": "https://news.ycombinator.com/item?id=45873892", "by": "squidfunk", "date": "2025-11-10", "stance": "recommend", "quote": "If Material for MkDocs ticks off all or most of the boxes, you can definitely start using it", "excerpt": "Zensical team here. It's perfectly usable \u2013 we're of course building our own docs with it and the first users have already switched \u2013 but you have to have an eye on compatibility. Whether you can switch right now largely depends on which plugins you're using from the MkDocs ecosystem. We have an entire section on compatibility.[1] If Material for MkDocs ticks off all or most of the boxes, you can definitely start usi", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733948512, "item_id": 45871782, "url": "https://news.ycombinator.com/item?id=45871782", "by": "mroche", "date": "2025-11-09", "stance": "recommend", "quote": "I am a massive Material for MkDocs fan", "excerpt": "> That said, if pressed, I\u2019d recommend AsciiDoc over any Markup flavor for a greenfield project _today_. Likewise for me as well, and I am a massive Material for MkDocs fan. Markdown is certainly simple to use and gets the job done, but AsciiDoc just provides so much out of the box without hurting my eyes like reStructuredText (used by Sphinx) does. It also helps that's there's effectively one type of AsciiDoc I'm aw", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733947713, "item_id": 45871732, "url": "https://news.ycombinator.com/item?id=45871732", "by": "parser_error", "date": "2025-11-09", "stance": "recommend", "quote": "I'm using mkdocs+material for one site (and it's great)", "excerpt": "This looks very interesting, I'm using mkdocs+material for one site (and it's great) but trying to find a good solution for more complex docs. Is there anything planned like 11ty's data files[1]? For example, I can pass it a JSON file, or a TOML file, and have it generate one HTML page per document in that file using their pagination system in a hacky way, and add those pages to collections for grouping in navigation", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}]}], "caveats": [], "who": [{"by": "finallyspeaking", "context": "Longtime tech writer", "url": "https://news.ycombinator.com/item?id=45871117", "date": "2025-11-09"}], "tags": [], "use_cases": ["documentation site", "docs theme and generator"], "compared": [{"slug": "zensical", "name": "Zensical", "co": 7, "switched_from": 0, "switched_to": 1}, {"slug": "mkdocs", "name": "MkDocs", "co": 3, "switched_from": 0, "switched_to": 0}], "makers": [], "threads": [{"url": "https://news.ycombinator.com/item?id=45865189", "title": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team", "mentions": 7}, {"url": "https://news.ycombinator.com/item?id=47482185", "title": "The Slow Collapse of MkDocs", "mentions": 2}], "sentiment_by_month": {"2025-11": {"compare": 1, "neutral": 2, "recommend": 2}, "2025-12": {}, "2026-01": {}, "2026-02": {}, "2026-03": {"neutral": 2}, "2026-04": {}, "2026-05": {}, "2026-06": {}, "2026-07": {}, "2026-08": {}, "2026-09": {}, "2026-10": {}}, "quotes": [{"id": 760298640, "item_id": 47518665, "url": "https://news.ycombinator.com/item?id=47518665", "by": "digital_voodoo", "date": "2026-03-25", "stance": "neutral", "quote": "settle with Material MkDocs", "excerpt": "As a non-technical person (not a dev, not a SWE, just a curious and selftaught tinkerer), I only want my _local_ markdown files to render as a beautiful - or at least, clean - webpage, to ease reading and sharing. No Github involved, no contorsionism needed. Just local md files. It should not be that complicated, at least that's what I felt. Those were the only requirements that made me settle with Material MkDocs, a", "context": "", "use_case": "", "switched_from": "", "story": "The Slow Collapse of MkDocs"}, {"id": 759832833, "item_id": 47489552, "url": "https://news.ycombinator.com/item?id=47489552", "by": "josiahpeters", "date": "2026-03-23", "stance": "neutral", "quote": "we just adopted Material for MK Docs about 12 months ago.", "excerpt": "Of course, we just adopted Material for MK Docs about 12 months ago. I\u2019ve been looking at Zensical https://zensical.org/ as a replacement, but I couldn\u2019t fully reason why they went off and did their own thing. I wasn\u2019t sure if it was a money grab or what their motivation was. This article provided the context I needed to understand the why. We\u2019re going to definitely give them a shot.", "context": "", "use_case": "documentation site", "switched_from": "", "story": "The Slow Collapse of MkDocs"}, {"id": 733982273, "item_id": 45873892, "url": "https://news.ycombinator.com/item?id=45873892", "by": "squidfunk", "date": "2025-11-10", "stance": "recommend", "quote": "If Material for MkDocs ticks off all or most of the boxes, you can definitely start using it", "excerpt": "Zensical team here. It's perfectly usable \u2013 we're of course building our own docs with it and the first users have already switched \u2013 but you have to have an eye on compatibility. Whether you can switch right now largely depends on which plugins you're using from the MkDocs ecosystem. We have an entire section on compatibility.[1] If Material for MkDocs ticks off all or most of the boxes, you can definitely start usi", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733948512, "item_id": 45871782, "url": "https://news.ycombinator.com/item?id=45871782", "by": "mroche", "date": "2025-11-09", "stance": "recommend", "quote": "I am a massive Material for MkDocs fan", "excerpt": "> That said, if pressed, I\u2019d recommend AsciiDoc over any Markup flavor for a greenfield project _today_. Likewise for me as well, and I am a massive Material for MkDocs fan. Markdown is certainly simple to use and gets the job done, but AsciiDoc just provides so much out of the box without hurting my eyes like reStructuredText (used by Sphinx) does. It also helps that's there's effectively one type of AsciiDoc I'm aw", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733947713, "item_id": 45871732, "url": "https://news.ycombinator.com/item?id=45871732", "by": "parser_error", "date": "2025-11-09", "stance": "recommend", "quote": "I'm using mkdocs+material for one site (and it's great)", "excerpt": "This looks very interesting, I'm using mkdocs+material for one site (and it's great) but trying to find a good solution for more complex docs. Is there anything planned like 11ty's data files[1]? For example, I can pass it a JSON file, or a TOML file, and have it generate one HTML page per document in that file using their pagination system in a hacky way, and add those pages to collections for grouping in navigation", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733937873, "item_id": 45871117, "url": "https://news.ycombinator.com/item?id=45871117", "by": "finallyspeaking", "date": "2025-11-09", "stance": "neutral", "quote": "finally, to Markup with the Material for MkDocs project, as a sponsor", "excerpt": "I\u2019m delighted to see this project evolving and look forward to following its development! I\u2019ve used just about every markup technology over my (many) years as a tech writer, from troff macros, to SGML/DocBook and then XML/DITA, and finally, to Markup with the Material for MkDocs project, as a sponsor. Each has its strengths and weaknesses, but for enabling contributors outside the tech writing community, simpler sour", "context": "Longtime tech writer", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733931873, "item_id": 45870742, "url": "https://news.ycombinator.com/item?id=45870742", "by": "perpil", "date": "2025-11-09", "stance": "neutral", "quote": "Its predecessor (mkdocs material) supported blogs via a plugin", "excerpt": "Its predecessor (mkdocs material) supported blogs via a plugin and rss feeds via a mkdocs plugin (https://guts.github.io/mkdocs-rss-plugin/). I don't believe it supports blogs yet according to this: https://zensical.org/compatibility/#phased-transition-strategy but will in the next phase when it supports plugins. It doesn't support loading content from a database that I'm aware of, it uses markdown files on disk as i", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733910017, "item_id": 45869376, "url": "https://news.ycombinator.com/item?id=45869376", "by": "squidfunk", "date": "2025-11-09", "stance": "neutral", "quote": "", "excerpt": "Excellent question. We're not using differential dataflow (DD), but are rolling our own differential runtime. It's basically functions stitched together with operators, heavily inspired by DD and RxJS, and is optimized for performance and ease of use. The decision to go from scratch allows us to provide something that, IMHO, is much simpler to work with than DD and Rx, as our goal is to allow an ecosystem to evolve, ", "context": "", "use_case": "Docs theme and generator", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}, {"id": 733878577, "item_id": 45867411, "url": "https://news.ycombinator.com/item?id=45867411", "by": "squidfunk", "date": "2025-11-09", "stance": "compare", "quote": "You can use the classic Material for MkDocs look with Zensical by adding a single line of configuration", "excerpt": "Creator of Zensical here! As always, it's a matter of taste. We felt the original look was a little date. You can use the classic Material for MkDocs look with Zensical by adding a single line of configuration[1]. This works because the HTML is exactly the same right now. Most users favor the new look over the old one. [1]: https://zensical.org/docs/setup/basics/#theme-variant", "context": "", "use_case": "", "switched_from": "", "story": "Zensical \u2013 A modern static site generator built by the Material for MkDocs team"}]}