mkdocs-material: Open Source Documentation & Knowledge Base

What is mkdocs-material?

What it is

Material for MkDocs is a documentation framework built on top of MkDocs, the static site generator for project documentation. It lives in the Python ecosystem and is distributed as a theme plus an accompanying set of plugins, so authors write documentation in Markdown and MkDocs builds it into a static site that the theme renders. The project is licensed under MIT, has existed for eleven years, and is maintained as an open-source project with more than 27,000 stars and over 4,000 forks on GitHub.

The concrete problem it solves is the gap between writing documentation and publishing something professional. Without a framework, teams either hand-build HTML, CSS and JavaScript, or they hand the backbone of their product knowledge to a third-party platform. Material for MkDocs removes both costs: it lets authors focus on content, produces the site automatically, and keeps the complete sources and outputs in the owner's hands. The project states that its theme is trusted by more than 50,000 individuals and organizations, including both industry users and open-source projects.

Key capabilities

Markdown authoring: documentation is written in Markdown, with no need to know HTML, CSS or JavaScript.
Built-in search: the generated site is searchable.
Responsive layout: the theme adapts automatically to desktop, tablet and mobile screens.
More than 60 languages supported.
Customization: colors, fonts, language, icons, logo and more are changed through configuration lines.
Extensibility: an ecosystem of plugins and options alters appearance and behavior.
Small footprint and fast rendering, aimed at strong performance and search engine rankings.
Static output, with the sources and the built site owned by the project rather than a hosted platform.

Who uses it and how

Open-source projects publishing reference documentation for libraries, frameworks and tools, including FastAPI, Electron, Apache Iceberg and Crystal.
Companies producing public engineering and product documentation, including Atlassian, AWS, Google, Microsoft, Netflix, Red Hat, Salesforce and Siemens.
Research and academic organizations, such as ArXiv, CERN and Harvard, which publish documentation sites from Markdown sources.
Teams that want to keep documentation inside their own repositories and hosting, with the theme applied at build time through the MkDocs configuration file.

Getting started

Install with pip using pip install mkdocs-material, then set theme: name: material in the project's mkdocs.yml. Detailed installation instructions, configuration options and a live demo are published at squidfunk.github.io/mkdocs-material.

When to use it — and when not to

It is a strong fit when a team wants documentation sources and outputs under its own control rather than inside a third-party publishing platform, and when the team already works in Python or is willing to adopt MkDocs. A self-hoster must still run the ordinary MkDocs build and deployment pipeline, including a static host or CI job, and any pieces added through plugins. The facts do not describe a hosted offering, so the tool is not a substitute for a fully managed documentation service.

project readme (upstream, from github) — read inline

A powerful documentation framework on top of MkDocs

Write your documentation in Markdown and create a professional static site for your Open Source or commercial project in minutes – searchable, customizable, more than 60 languages, for all devices.

Check out the demo – squidfunk.github.io/mkdocs-material.

Silver sponsors

Bronze sponsors

Everything you would expect

It's just Markdown

Focus on the content of your documentation and create a professional static site in minutes. No need to know HTML, CSS or JavaScript – let Material for MkDocs do the heavy lifting for you.

Works on all devices

Serve your documentation with confidence – Material for MkDocs automatically adapts to perfectly fit the available screen estate, no matter the type or size of the viewing device. Desktop. Tablet. Mobile. All great.

Made to measure

Make it yours – change the colors, fonts, language, icons, logo, and more with a few lines of configuration. Material for MkDocs can be easily extended and provides many options to alter appearance and behavior.

Fast and lightweight

Don't let your users wait – get incredible value with a small footprint by using one of the fastest themes available with excellent performance, yielding optimal search engine rankings and happy users that return.

Maintain ownership

Own your documentation's complete sources and outputs, guaranteeing both integrity and security – no need to entrust the backbone of your product knowledge to third-party platforms. Retain full control.

Open Source

You're in good company – choose a mature and actively maintained solution built with state-of-the-art Open Source technologies, trusted by more than 50,000 individuals and organizations. Licensed under MIT.

Quick start

Material for MkDocs can be installed with pip:

pip install mkdocs-material

Add the following lines to mkdocs.yml:

theme:
  name: material

For detailed installation instructions, configuration options, and a demo, visit squidfunk.github.io/mkdocs-material

Trusted by ...

... industry leaders

ArXiv, Atlassian, AWS, Bloomberg, CERN, Datadog, Google, Harvard, Hewlett Packard, HSBC, ING, Intel, JetBrains, LinkedIn, Microsoft, Mozilla, Netflix, OpenAI, Red Hat, Roboflow, Salesforce, SIEMENS, Slack, Square, Uber, Zalando

... and successful Open Source projects

Amp, Apache Iceberg, Arduino, Asahi Linux, Auto-GPT, AutoKeras, BFE, CentOS, Crystal, eBPF, ejabberd, Electron, FastAPI, FlatBuffers, {fmt}, Freqtrade, GoReleaser, GraphRAG, Headscale, HedgeDoc, Hummingbot, Knative, Kubernetes, kSQL, LeakCanary, LlamaIndex, NetBox, Nokogiri, OpenAI, OpenFaaS, OpenSSL, Orchard Core, Percona, Pi-Hole, Polars, Pydantic, PyPI, Quivr, Renovate, RetroPie, Ruff, Supervision, Textual, Traefik, Trivy, Typer, tinygrad, Ultralytics, UV, Vapor, WebKit, WTF, ZeroNet

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Frequently asked questions

Is mkdocs-material free to use?

mkdocs-material is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does mkdocs-material do?

Documentation that simply works

What is mkdocs-material written in?

mkdocs-material is primarily written in Python. Its source is publicly available at https://github.com/squidfunk/mkdocs-material, and it has 27,596 GitHub stars.