LULunar5227·Sep 25, 2025Submission
MkDocs – Update on our foundational work
6 points · Open discussionsquidfunk
mkdocs-material
Python2018–2025
squidfunk / mkdocs-material
mkdocs-material
Documentation that simply works
10Distinct people
15Mentions
0Explicit recommenders
27.6KGitHub stars
What to know before exploring
What it is
Documentation that simply works
GitHub
Where it is used
No documented product use has been verified yet.
What people are saying
No recommendation phrase was found in the indexed comments.
No classified warning is attached to this page. Read the discussions before treating silence as approval.
Also in these discussions
No other repository is repeatedly linked in the same discussions.
This week on Hacker News
Nov 7–Nov 14 UTC · Direct repository links and separately labeled related project stories. Indexed through 11/14/2026, 12:54:37 PM UTC.
No direct repository links were found in the indexed HN discussions over the past seven days. Older discussions are available below.
Mentions over time
HN mentions by year15 dated mentions
Observed mentions: 2018-08-08 17:18:01 UTC to 2025-09-25 13:54:42 UTC.
Counts come from the repository’s dated source evidence. Index cutoff: 2026-11-02 08:16:59 UTC.
View mention counts and date ranges
| Period | Start (UTC) | End (exclusive, UTC) | Mentions | Submissions | Comments |
|---|---|---|---|---|---|
| 2018 | 2018-01-01 00:00:00 UTC | 2019-01-01 00:00:00 UTC | 2 | 0 | 2 |
| 2019 | 2019-01-01 00:00:00 UTC | 2020-01-01 00:00:00 UTC | 1 | 0 | 1 |
| 2020 | 2020-01-01 00:00:00 UTC | 2021-01-01 00:00:00 UTC | 0 | 0 | 0 |
| 2021 | 2021-01-01 00:00:00 UTC | 2022-01-01 00:00:00 UTC | 1 | 0 | 1 |
| 2022 | 2022-01-01 00:00:00 UTC | 2023-01-01 00:00:00 UTC | 4 | 1 | 3 |
| 2023 | 2023-01-01 00:00:00 UTC | 2024-01-01 00:00:00 UTC | 6 | 4 | 2 |
| 2024 | 2024-01-01 00:00:00 UTC | 2025-01-01 00:00:00 UTC | 0 | 0 | 0 |
| 2025 | 2025-01-01 00:00:00 UTC | 2026-01-01 00:00:00 UTC | 1 | 1 | 0 |
What Hacker News says
15 sourcesMaterial for MkDocs – Documentation that simply works
1 points · Open discussionFeatures tied to 'Piri Piri' funding goal
1 points · Open discussionused material for mkdocs - https://github.com/squidfunk/mkdocs-material . Its pretty neat.
In Show HN: OpenObserve – Elasticsearch/Datadog alternativeThank you! You can upvote it here (and perhaps share some ideas?): https://github.com/squidfunk/mkdocs-material/discussions/468...
In Tufte CSSRelease Mkdocs-Material-9.0.0b1
1 points · Open discussion> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish
This, except for normals, sort of exists:
Craft: https://www.craft.do/solutions/businesses
Default is internal only, but you can allow sharing, which creates a web URL that can be privately or publicly shared (and can be on your own custom domain).
It has versioning, it has comments, it has real time multi-editor collaboration. An entire conference room, in person and virtual, can co-edit in true real time without anything blowing up, a feat not to be tried in Word, or even Google Docs.
Most firms should stop looking and just try Craft. Encourage everyone to do everything there, see what happens.
Note bene
Read the rest
: it happily imports markdown, also exports Word, PDF, Markdown, and Textbundle, and can feed a static site gen.
They also keep busy: https://www.craft.do/whats-new
// I use Obsidian for myself, but Craft to collaborate with non-engineers. I've also been known to recommend FOAM to engineering teams, coupled with mkdocs and a good theme for static site gen, such as material for mkdocs:
https://foambubble.github.io/foam/
https://github.com/squidfunk/mkdocs-material
For eng teams already living in VS Code, it's hard to beat PKM where you already are.
I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.
[1] https://github.com/squidfunk/mkdocs-material#trusted-by-
[2] https://github.com/tiangolo/fastapi
In Markdoc: Stripe's Markdown-based authoring frameworkHi, GitLab team member here.
GitLab had 2 separate projects before merging into https://gitlab.com/gitlab-org/gitlab in 2019 as a single code base for both, community and enterprise edition.
https://about.gitlab.com/blog/2019/08/23/a-single-codebase-f...
The source code portions use different licenses which are explained in https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE for each directory, etc.
For your use case, speaking with my personal hat:
It depends if you'd prefer the proprietary extensions being source available or not. If they should be visible and are protected with a license, a single code base is a good approach imho.
An alternative way could be treating the OSS project as a Git submodule, including it in your CI/CD pipelines, and dev environments. In these steps, you'll fetch the modules and build everything togeth
Read the rest
er.
An example I just thought of: MkDoc Material Theme. You'll get the OSS project at https://github.com/squidfunk/mkdocs-material and the paid insiders version is made available as private project. https://squidfunk.github.io/mkdocs-material/insiders/ CI/CD and deployments then require an extra step to install the proprietary package, example in https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/.gitla...
Multiple separate repositories need good onboarding documentation, and the 5-min-to-success when spinning up a dev environment to contribute. That challenge exists with a single codebase too. In the end, it really depends on the strategy of source available or not :-)
Sure! The README links [1] to several installations used by large Open Source projects and companies. Some prominent examples:
- https://fastapi.tiangolo.com/
- https://crystal-lang.org/reference/
- https://docs.pi-hole.net/
- https://docs.openfaas.com/
- https://mozillafoundation.github.io/engineering-handbook/
- https://microsoft.github.io/code-with-engineering-playbook/
[1]: https://github.com/squidfunk/mkdocs-material#trusted-by-
In Technical documentation that just worksThis is nice. However, isn't this just having a boilerplate starter kit for deploying MkDocs sites to various providers (GitHub Pages, GitLab, AWS Amplify, etc) using the MkDocs Material template theme built by Squidfunk (https://github.com/squidfunk/mkdocs-material)?
If so, it would probably be good to add a citation if nothing else to raise awareness and support for Squidfunks beautiful and well maintained MkDocs theme https://squidfunk.github.io/mkdocs-material/
Thanks!
In Show HN: MkDocs Material Boilerplate – Starter KitI've found mkdocs to be fantastic for this, especially when paired with its material theme:
https://www.mkdocs.org/
https://github.com/squidfunk/mkdocs-material
There's a docker image that makes getting started with both quite easy:
https://squidfunk.github.io/mkdocs-material/getting-started/...
In Show HN: Docute – Fast way to create a documentation siteI'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs.
POSITIVES OF MkDocs over Sphinx
* Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText.
* MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/.
* Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/m...)
* Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjk
Read the rest
ing/1upkeyboard-docs/blob/master/....)
The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience):
* If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc).
* Sphinx seems better for auto documentation for APIs and other code documentation.