Skip to main content

MaterialX


MaterialX, the next generation of mkdocs-material, build beautiful sites the way you already know and love, based on mkdocs-material-9.7.1 and named X, it provides ongoing maintenance and updates.

Why MaterialX ?

The MkDocs project is nearing its end due to personal issues involving its original author. He has ceased updates for MkDocs and intends to release a completely new 2.0 version as a replacement. However, this new version is entirely incompatible with the existing ecosystem. It is an entirely separate project that merely carries the MkDocs name, and an accidental upgrade will result in devastating damage.

As a result, to break free from dependency on MkDocs, the team behind the popular mkdocs-material theme framework has discontinued its maintenance and shifted to developing an entirely new alternative project named Zensical. While it adopts a new architecture and eliminates dependency on MkDocs, it still lacks many features. In addition, it is incompatible with the existing MkDocs ecosystem, making many existing plugins unavailable. This imposes certain migration costs on users, and its stability remains unproven.

To ensure the continued stable operation of existing MkDocs projects and ecosystem, a new community-driven successor to MkDocs has emerged: ProperDocs (based on MkDocs 1.6.1). It will provide ongoing updates and maintenance while remaining fully compatible with the original MkDocs ecosystem.

Similarly, mkdocs-material also has a new successor: MaterialX (based on mkdocs-material 9.7.1). It provides ongoing maintenance and updates, with full compatibility with the original ecosystem and zero migration costs.


In short: MaterialX + ProperDocs is an equivalent replacement for mkdocs-material + mkdocs and provides ongoing maintenance and updates.

MaterialX preserves the rich features and stability of the mkdocs-material project, while delivering new features and broad compatibility, and provides ongoing maintenance and updates.


Update Highlights

  • Added Markdown source support for AI agents to provide structured content, reducing token consumption by over 80%
  • Refactored the search functionality with a brand-new architecture, supporting the Pagefind framework, and greatly improving search quality and indexing efficiency. It supports multi-provider mode, chunked indexing, on-demand loading, index compression, multilingual search and cross-domain search. It is suitable for various complex scenarios and large-scale sites, and can handle sites with more than 100,000 pages, see Search
  • Added code block download & auto-collapse/expand long code blocks features, see Code blocks
  • Added the new Steps component for clearer, more intuitive display of procedures and workflows, see Steps
  • Enhanced blog: 4x performance improvement, CJK support, sharing module, see Blog
  • Added next-generation date & author plugin, see: Add document dates & authors
    • It's 20-500 times faster than git-revision-date-localized and git-authors, and works in any environment (no-Git, Git environments, Docker, all CI/CD build systems, etc.).
    • Completely resolved date and time infrastructure issues, enabling the project to support automated date processing. Manual date configuration is no longer required for any feature, including: page date display, blog post dates, blog date archives, blog list sorting, sitemap.xml (lastmod - SEO improvements), RSS feeds, recently updated section, search ranking, and more
  • Added Recent Updated module, see: Add recent updates module
    • Automatically generates document summaries (no manual configuration needed)
    • Intelligently estimates reading time, supporting all languages (CJK languages + Space-delimited languages)
  • Refactored the mobile TOC component for seamless NAV and TOC experience on mobile (better interactive experience)
  • Perfectly fixed the issue where swipe gestures would penetrate when the sidebar drawer was active on mobile (prone to accidental operations and poor user experience; unresolved in Zensical and Material)
  • Significantly polished the UX and details on mobile devices
    • Moved the "Back to top" container to the bottom, aligning with natural interaction logic
    • Optimized the show/hide sensitivity of the "Back to top" container
    • Added indent guide lines and active link accent colors for the TOC
  • Added the modern Liquid Glass theme, allows setting the topbar background color in the Liquid Glass theme to support backgrounds with different color schemes, see Topbar style
  • For more details, see Changelog

Quick Start

1 - Installation:

pip install mkdocs-materialx

2 - Configure materialx theme to mkdocs.yml:

theme:
  name: materialx

3 - Start a live preview server with the following command for automatic open and reload:

for MkDocs :

mkdocs serve --livereload -o

for ProperDocs :

properdocs serve -o

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


Chat Group

Discord: https://discord.gg/cvTfge4AUy

Metadata

Release files for mkdocs-materialx 10.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-materialx 10.2.2
File Size Uploaded Provenance Actions
mkdocs_materialx-10.2.2.tar.gz 4.3 MB With provenance Details for mkdocs_materialx-10.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-materialx 10.2.2
File Interpreter ABI Platform Actions
mkdocs_materialx-10.2.2-py3-none-any.whl Python 3 none any Details for mkdocs_materialx-10.2.2-py3-none-any.whl

Total release size: 14.5 MB

Release files / mkdocs_materialx-10.2.2.tar.gz

Download URL mkdocs_materialx-10.2.2.tar.gz
Size 4.3 MB
Tags Source
SHA-256 checksum
How to use checksums
8806bcc53db72ae02937e3e7171a58fe47dc628ba904f9510e6ab5c3561b3529
BLAKE2b-256 checksum
How to use checksums
bd1dd542f5028b29edc7931917e3a2e533a166c1b13d5e2b57836f838d13811b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Release files / mkdocs_materialx-10.2.2-py3-none-any.whl

Download URL mkdocs_materialx-10.2.2-py3-none-any.whl
Size 10.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
887fd8a7dede53882dd3e00f2be3db94ee531aad0c361cf8f97990bf3c57cd1b
BLAKE2b-256 checksum
How to use checksums
e403d7ff2670ab8c637ff74f42c317bb923b7ad9928da5a8248198f19f803e22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Security for mkdocs-materialx 10.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mkdocs_materialx-10.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page