Skip to content

Blog

  • 2024年8月19日

  • 一般来说

    ¥ in

  • 阅读需14分钟

    ¥ 14 min read

为 MkDocs 转换材料

¥Transforming Material for MkDocs

我们正在开发一系列令人惊叹的功能，这其中涉及一些幕后工作，现在我们准备通过一系列博文来分享。在这里，我们将概述我们的目标、正在开发的功能、那些让我们夜不能寐的事情，以及我们对开源的承诺。

¥We are working on an amazing set of features which has required some behind-the-scenes work we are now ready to share in a series of posts. Here, we give an overview of our goals, features in the making, things that kept us up at night, and our commitment to Open Source.

我们知道距离上次更新已经有一段时间了，因此我们迫切地想与您分享 Material for MkDocs 及其周边的最新动态。在 2024 年的大部分时间里，我们一直专注于改造 Material for MkDocs 的核心，为最常被请求的新功能、互联功能奠定基础。

¥We know it's been quite a while since our last update, which is why we're eager to share what's happening in and around Material for MkDocs with you. For the largest part of 2024, we've been focused on transforming the core of Material for MkDocs preparing the ground for new, interconnected features that are amongst the most frequently requested.

本文是系列文章的第一篇，我们将探讨如何通过改进信息检索功能来支持用户，更好地支持多语言网站和版本控制，并提升整体创作体验。我们将概述项目发展的愿景，并介绍我们目前的工作内容。在本篇及后续博文中，我们将与您分享我们的进展，并期待听到您的想法。

¥This article is the first in a series where we'll explore how we aim to support our users through improved information retrieval, provide better support for multi-lingual sites and versioning, as well as improve the overall authoring experience. We outline our vision for the projects' evolution and describe what we have been working on. In this and the coming blog posts, we will share our progress with you, and we're excited to hear your thoughts.

  • 2023年11月30日

  • 一般来说

    ¥ in

  • 阅读需 1 分钟

    ¥ 1 min read

向您的项目添加徽章

¥Adding a badge to your project

您喜欢使用 Material for MkDocs 吗？分享您的爱！现在，您可以在项目的 README 文件中添加徽章，以表明您的项目是使用 Material for MkDocs 构建的。

¥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.

MkDocs 徽标的素材刚刚添加到Simple Icons中， Shields.io使用它来将徽标包含在徽章中。我们为您生成了一个徽章，您可以将其添加到项目的 README 中：

¥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:

  • 2023年10月2日

  • 一般来说

    ¥ in

  • 阅读需3分钟

    ¥ 3 min read

Gitter 的落幕：迈向高效的社区参与

¥Sunsetting Gitter: Towards Efficient Community Engagement

当我们开始围绕 MkDocs 的 Material 组建团队时，我们决定在 2023 年 10 月 13 日关闭并存档我们的 Gitter 频道，转而使用 GitHub Discussions。

¥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.

为了改进 MkDocs 材料维护流程并支持社区，我们审查了不同沟通渠道的使用情况。目前， Gitter和GitHub 讨论区都允许向社区寻求支持，并讨论想法和问题。在过去几周，我们开始质疑这种重复是否符合我们项目的最佳利益。这篇文章解释了我们做出这一决定背后的原因。

¥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 加快文档构建速度

¥Using git sparse-checkout for faster documentation builds

利用 GitHub Actions 中的 git sparse-checkout，我们可以加快存储库中的文档构建速度，将签出时间从 20 到 30 秒缩短到仅 2 秒。

¥Leveraging 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.

在持续集成 (CI) 工作流中，开发一种高效的文档构建方法至关重要，尤其是在像我们这样拥有数千条提交记录的大型代码库中工作时。当然，我们希望快速高效地构建文档，确保快速高效的工作流程。在使用出色的git-committers和git-revision-date-localized插件在每页底部显示文档贡献者和日期时，我们需要设置fetch-depth: 0 ，这导致代码库的检出时间需要 20 到 30 秒。通过利用GitHub Actions中的git sparse-checkout功能，检出时间缩短至 2 秒。

¥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.

  • 2022年9月12日

  • 在博客中

    ¥ in Blog

  • 阅读需 4 分钟

    ¥ 4 min read

博客支持刚刚发布

¥Blog support just landed

嘿！您正在浏览我们全新的博客，它使用全新的内置博客插件构建。使用此插件，您可以轻松创建博客，与文档同步，或独立运行。

¥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.

正如过去几年许多用户所期望的那样，Material 中对博客的支持是 MkDocs 功能集中亟待解决的问题。虽然大家都认为博客支持是一个盲点，但 MkDocs 能否扩展以实现我们熟知的Jekyll及其同类产品中的博客功能尚不明确。内置的博客插件证明了，在 MkDocs 之上构建博客引擎是可行的，这样就可以在文档之外创建技术博客，或者将其作为主要内容。

¥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.

  • 2022年5月5日

  • 在搜索中

    ¥ in Search

  • 阅读需2分钟

    ¥ 2 min read

中文搜索支持 – 中文搜索​支持

¥Chinese search support – 中文搜索​支持

Insiders 为内置搜索插件添加了实验性的中文支持——鉴于中国用户数量众多，这一功能已被呼吁许久。

¥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.

继美国和德国之后，MkDocs 用户使用 Material 的第三大来源国是中国。长期以来，内置搜索插件无法正确分割中文字符，主要是因为缺少用于搜索分词和词干提取的lunr-languages支持。最新的 Insiders 版本为内置搜索插件添加了期待已久的中文支持，这是许多用户一直呼吁的。

¥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年12月27日

  • 一般来说

    ¥ in

  • 阅读需6分钟

    ¥ 6 min read

过去、现在和未来

¥The past, present and future

2021 年对于这个项目来说是辉煌的一年，因为我们推出了许多出色的新功能，用户数量显著增长，并利用 GitHub 赞助商使项目可持续发展。

¥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.

如今，在为您的技术文档项目选择静态站点生成器和主题时， MkDocs和 Material for MkDocs 是最受欢迎的选择之一。Material for MkDocs 确保您的内容始终完美呈现给受众，无论屏幕分辨率或设备功能如何。它已经发展成为一个技术写作框架，提供许多功能，其中一些功能在其他静态站点生成器中尚不可用。然而，这远未结束，因为 2022 年将带来一些有趣的新功能。

¥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.

  • 2021年9月26日

  • 在搜索中

    ¥ in Search

  • 阅读需 4 分钟

    ¥ 4 min read

从搜索中排除内容

¥Excluding content from search

最新的 Insiders 版本带来了三种新的简单方法，可以从搜索索引中排除文档的专用部分，从而实现更细粒度的控制。

¥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.

两周前，Material for MkDocs Insiders 发布了一款全新的搜索插件，不仅大幅提升了易用性，还优化了搜索索引的速度和大小。有趣的是，正如上一篇博客文章中所讨论的，我们只是触及了现有功能的冰山一角。此版本带来了一些实用功能，提升了写作体验，允许更精细地控制 Markdown 文件中哪些页面、章节和区块应该被内置搜索功能索引。

¥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.

搜索：更好、更快、更小

¥Search: better, faster, smaller

这是我们如何彻底重建客户端搜索的故事，在提供更好的用户体验的同时，使其变得更快、更小。

¥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.

Material for MkDocs 的搜索功能是迄今为止其最优秀、最受欢迎的资产之一：多语言、离线功能，以及最重要的：全客户端。它提供了一种解决方案，使您的文档用户能够立即找到他们正在搜索的内容，而无需管理额外的服务器。然而，即使已经进行了多次迭代，仍有一些改进空间，因此我们从头开始重建了搜索插件和集成。本文将揭示新搜索的内部原理、它为何比以前的版本更强大，以及即将推出的功能。

¥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.