You enjoy working with Material for MkDocs? Share the love! You can now add a badge to your project's README, showing that your project is built with Material for MkDocs.
Material for MkDocs' logo was just added to Simple Icons, which is used by Shields.io to include logos in badges. We generated a badge for you, which you can add to your project's README:
As we're starting to build a team around Material for MkDocs, we've decided to sunset and archive our Gitter channel on October 13, 2023 in favor of GitHub Discussions.
As part of our efforts to improve the processes for maintaining Material for MkDocs and for supporting the community, we have reviewed the use of different communication channels. At the moment, both Gitter and GitHub Discussions allow to ask the community for support and to discuss ideas and issues. In the past weeks, we have begun to question whether this duplication is in the best interest of our project. This post explains the rationale behind our decision.
git sparse-checkout for faster documentation buildsLeveraging git sparse-checkout in GitHub Actions enabled us to speed up documentation builds in our repository, cutting checkout times from 20 to 30 seconds to just 2 seconds.
Developing an efficient approach to build documentation in CI workflows is essential, especially when working in large repositories with thousands of commits, like ours. Of course, we want to build documentation quickly and efficiently, ensuring fast and productive workflows. When using both the wonderful git-committers and git-revision-date-localized plugins to display document contributors and dates at the bottom of each page, we are required to set fetch-depth: 0, which resulted in checkout times of 20 to 30 seconds on our repository. By leveraging git sparse-checkout within GitHub Actions, check out time was brought down to 2 seconds.
Hey there! You're looking at our new blog, built with the brand new built-in blog plugin. With this plugin, you can easily build a blog alongside your documentation or standalone.
Proper support for blogging, as requested by many users over the past few years, was something that was desperately missing from Material for MkDocs' feature set. While everybody agreed that blogging support was a blind spot, it was not obvious whether MkDocs could be extended in a way to allow for blogging as we know it from Jekyll and friends. The built-in blog plugin proves that it is, after all, possible to build a blogging engine on top of MkDocs, in order to create a technical blog alongside your documentation, or as the main thing.
Insiders adds experimental Chinese language support for the built-in search plugin – a feature that has been requested for a long time given the large number of Chinese users.
After the United States and Germany, the third-largest country of origin of Material for MkDocs users is China. For a long time, the built-in search plugin didn't allow for proper segmentation of Chinese characters, mainly due to missing support in lunr-languages which is used for search tokenization and stemming. The latest Insiders release adds long-awaited Chinese language support for the built-in search plugin, something that has been requested by many users.
2021 was a fantastic year for this project as we shipped many new awesome features, saw significant user growth and leveraged GitHub Sponsors to make the project sustainable.
Today, together, MkDocs and Material for MkDocs are among the most popular options when it comes to choosing a static site generator and theme for your technical documentation project. Material for MkDocs ensures that your content is always perfectly presented to your audience, regardless of screen resolution or device capabilities. It has evolved to a framework for technical writing, offering many features, some of which are yet to be found in other static site generators. However, we're far from the end, as 2022 is going to bring some interesting new capabilities.
The latest Insiders release brings three new simple ways to exclude dedicated parts of a document from the search index, allowing for more fine-grained control.
Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin, yielding massive improvements in usability, but also in speed and size of the search index. Interestingly, as discussed in the previous blog article, we only scratched the surface of what's now possible. This release brings some useful features that enhance the writing experience, allowing for more fine-grained control of what pages, sections and blocks of a Markdown file should be indexed by the built-in search functionality.
This is the story of how we managed to completely rebuild client-side search, delivering a significantly better user experience while making it faster and smaller at the same time.
The search of Material for MkDocs is by far one of its best and most-loved assets: multilingual, offline-capable, and most importantly: all client-side. It provides a solution to empower the users of your documentation to find what they're searching for instantly without the headache of managing additional servers. However, even though several iterations have been made, there's still some room for improvement, which is why we rebuilt the search plugin and integration from the ground up. This article shines some light on the internals of the new search, why it's much more powerful than the previous version, and what's about to come.