Skip to content

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

请注意，本文的脚注中包含了一些技术细节，特别是关于挑战的内容。如果您对这些细节不感兴趣，可以跳过。

¥Please note that this post includes several technical details in the footnotes, specifically on challenges. Feel free to skip them if you're not interested in the specifics.

成功故事

¥A success story

2024 年，Material for MkDocs 已稳固确立了其在文档框架领域的领先地位，截至撰写本文时，每月下载量已超过 500 万次。最初由@squidfunk的个人项目开发，如今已发展成为一个多功能资源，可用于创建综合文档站点、个人网站、博客，尤其可用于管理组织内外的知识。

¥In 2024, Material for MkDocs has firmly established itself as a leading tool in the documentation framework landscape, with more than 5 million downloads each month as of this writing. What began as @squidfunk's personal project has evolved into a versatile resource for creating comprehensive documentation sites, personal websites, blogs, and notably, for managing knowledge both within and outside of organizations.

目前，GitHub 上近5 万个公共项目依赖于 Material for MkDocs，可见该框架已产生巨大影响。每月有成千上万的作者依靠我们向数百万用户提供文档。1 除了被许多流行的开源项目采用之外，Material for MkDocs 还受到AWS 、微软、西门子等大公司以及许多其他公司和个人的信任和资金支持。我们非常感谢大家的持续支持，这使我们能够将时间投入到这个项目中，让编写文档变得愉快。

¥With almost 50,000 public GitHub projects depending on Material for MkDocs, it's clear that the framework has made a substantial impact. Tens of thousands of authors rely on us to deliver documentation to millions of users each month.1 Beyond its adoption by many popular Open Source projects, Material for MkDocs is trusted and financially supported by major corporations such as AWS, Microsoft, and Siemens, among many other companies and individuals. We're very grateful for the continued support we receive, which allows us to devote our time to this project, making writing documentation enjoyable.

我们的用户尤其欣赏 Material for MkDocs 的易用性和简单的设置。它简化了流程，为您处理复杂的 Web 技术，让您只需几分钟即可构建一个可用于生产的静态网站，而无需花费数年时间掌握前端开发或 JavaScript。这使得它可供广泛的用户使用，无论其技术背景如何。此外，Material for MkDocs 采用 MIT 许可并免费使用，这有助于其广泛采用，并允许每个人都免费构建复杂的文档网站。

¥Our users particularly appreciate Material for MkDocs for its ease of use and straightforward setup. It simplifies the process by handling the complexities of web technologies for you, so you can build a production-ready static site in minutes without needing to invest years into mastering frontend development or JavaScript. This makes it accessible to a wide range of users, regardless of their technical background. Additionally, Material for MkDocs is MIT-licensed and free to use, which has contributed to its widespread adoption, and allows everybody to build sophisticated documentation sites at no cost.

我们的愿景是为您提供工具，让您掌控自己的文档，开发自己的流程，从而生成出色的文档，并避免即使是简单的操作也受制于昂贵的订阅服务。我们认为，这些工具不仅应易于设置和配置，以满足您的需求，还应允许您根据需要自由地进行进一步调整。正因如此，我们始终致力于确保我们的架构模块化且面向未来。2

¥Our vision is to provide you with the tools that allow you to own your docs, enable you to develop your own processes for producing amazing documentation and to avoid being locked into costly subscription services even for doing simple things. We believe it is important that these tools should be easy to set up and configure to suit your needs but should also give you the freedom to adapt them further, if needed. This is why we are always striving to ensure our architectures are modular and future-proof.2

挑战

¥Challenges

现在，让我们来谈谈我们的历程以及我们正在应对的具体挑战。“我们”指的是@squidfunk有幸围绕他的原创作品组建的优秀团队，这要感谢他从赞助商那里获得的资金支持。这个卓越的团队包括@alexvoss和@katharinalisalin ，他们在研究、开发和社区支持方面做出的宝贵贡献，对项目的持续成功至关重要。

¥Now, let's talk about our journey and the particular challenges we're addressing. With "we", we're referring to the incredible team that @squidfunk was fortunate to build around his original work, thanks to the financial support he receives from his sponsors. This remarkable team includes @alexvoss and @katharinalisalin, whose invaluable contributions in research, development, and community support have been essential to the project's ongoing success.

我们一起开始探索新技术，整合从用户那里收到的反馈，并从第一原则重新思考关键组件，为我们不断壮大的社区提供创建文档的最佳框架之一。

¥Together, we've started exploring new technologies, incorporating the feedback we received from our users, and rethinking critical components from first principles, serving our growing community one of the best frameworks to create documentation.

本节重点介绍我们一直关注的关键领域。

¥This section highlights the key areas we've been focusing on.

搜索和发现

¥Search and discovery

从我们的角度来看，搜索是任何高效文档网站的基石，它使用户能够快速找到所需信息。从一开始，我们就依赖于Lunr.js ，这是一个流行的客户端搜索库，它简化了文档网站的部署，无需外部服务。多年来，Lunr.js 为我们提供了良好的服务，它解答了使用 Material for MkDocs 构建的网站上的数百万个查询。然而，随着用户需求的不断变化，我们遇到了一些难以克服的限制。

¥From our perspective, search is a cornerstone of any effective documentation site, enabling users to swiftly locate the information they need. From the start, we've relied on Lunr.js, a popular client-side search library that has streamlined the deployment of documentation sites without needing an external service. Over the years, Lunr.js has served us well by answering millions of queries on sites built with Material for MkDocs. Yet, as our users' needs evolved, we encountered limitations that proved difficult to overcome.

我们了解到，Lunr.js 核心的BM25 排名算法（与许多其他搜索实现一样）并不适合高效稳定的预输入功能。添加新文档可能会影响现有排名，需要手动调整3 ，这既繁琐又难以扩展。此外，Lunr.js 还存在性能问题，这源于其设计未能充分利用现代 JavaScript 引擎和优化，导致其速度较慢且占用大量内存。4

¥We learned that the BM25 ranking algorithm at the core of Lunr.js (as in many other search implementations) isn't well-suited for effective and stable typeahead. Adding new documents can influence existing rankings, requiring manual adjustments3 that are cumbersome and hard to scale. Furthermore, Lunr.js has performance issues that stem from its design not fully leveraging modern JavaScript engines and optimizations, making it slower and memory-intensive.4

在过去的几年中，我们投入了大量资金来改善搜索体验。例如，扩展 Lunr.js 的功能以添加对丰富搜索预览和标记器前瞻的支持需要大量的工程工作。Lunr.js 允许使用管道函数自定义任务，例如词干提取、停用词过滤和修剪，但它使添加术语突出显示或其他排名方法等扩展变得尤为困难。再加上 Lunr.js自 2020 年以来一直没有维护，我们显然需要找到一个更强大的解决方案。我们研究了其他基于 JavaScript 的库来维持我们的客户端搜索，但没有一个满足我们的要求或达到我们的期望。

¥Over the last years, we've invested substantially into improving the search experience. For instance, expanding Lunr.js' functionality to add support for rich search previews and tokenizer lookahead demanded substantial engineering effort. Lunr.js allows to customize tasks such as stemming, stopword filtering, and trimming with pipeline functions, but it makes it particularly hard to add extensions like term highlighting or alternative ranking methods. Compounded by the fact that Lunr.js has been unmaintained since 2020, it became clear that we needed to find a more powerful solution. We've looked at alternative JavaScript-based libraries to keep our client-side search, but none met our requirements or lived up to our expectations.

为了应对这些挑战，我们着手开发一套全新的搜索系统，该系统基于基本原则，不仅能够匹敌 Lunr.js，甚至超越其功能。该系统从零开始构建，速度更快、更紧凑，最重要的是：模块化。它基于一个不断发展的核心，围绕着我们分离出来的两个核心概念——引擎和插件——进行开发，允许灵活地配置和组装文本索引、向量嵌入、过滤、排名、高亮等组件。它的每个部分都可以替换或扩展，使用户能够根据自己的特定需求定制搜索系统。

¥To address these challenges, we've embarked on developing a new search system from first principles that not only matches but already exceeds the capabilities of Lunr.js. Built from the ground up, this system is faster, more compact, and most importantly: modular. It is based on a growing core evolving around two core concepts we isolated to be essential – engines and plugins – allowing for flexible configuration and assembly of components like text indexing, vector embeddings, filtering, ranking, highlighting, and more. Every part of it can be replaced or extended, enabling users to tailor the search system to their specific needs.

我们的新搜索系统将以独立的 MIT 许可证开源项目形式发布，旨在处理各种场景——从小型博客到大型文档项目。当然，它支持离线使用，并可与客户端和服务器环境无缝集成。先进的排名系统提供精细的控制，与第三方服务的集成现在更加便捷。

¥Our new search system, which we will release as a separate MIT-licensed Open Source project, is designed to handle a wide range of scenarios — from small blogs to large documentation projects. Of course, it supports offline use and integrates seamlessly with both client and server environments. The advanced ranking system provides fine-tuned control, and integration with third-party services is now more straightforward.

目标 – 通过提供适应多种内容类型的搜索系统，使用户能够快速找到所需信息，同时使作者无需管理外部服务。

¥ Goal – Empower users to quickly find the information they need while freeing authors from managing external services, by providing a search system that adapts to diverse content types.

您可能想知道为什么它尚未可用。从零开始开发该系统并发掘其潜力的过程促使我们重新评估Material for MkDocs的核心概念。因此，我们决定推迟新搜索系统的发布，以便将其集成到我们已开始进行的更广泛的更新中。如果您继续阅读，您将了解我们决定采用这种方法的更多原因。

¥You might wonder why it's not yet available. The process of developing this system from scratch and uncovering its potential has led us to re-evaluate core concepts of Material for MkDocs. As a result, we've decided to postpone the release of the new search system to integrate it into the broader update that we've started to work on. If you keep on reading, you'll learn about further reasons why we've decided to follow this approach.

我们很高兴在本系列的下一篇文章中分享有关此更新的更多详细信息。

¥We're excited to share more details about this update in one of the next posts in this series.

翻译和版本控制

¥Translations and versioning

在 MkDocs 中支持多语言网站是我们论坛和与用户交流中最常被提及的功能，然而由于 MkDocs 本身并不支持多语言网站，因此它带来了巨大的挑战。版本控制也面临同样的问题，因为它涉及到多项目构建的同步。虽然 MkDocs 生态系统已经开发了各种插件和工具来解决这些问题，但仍有巨大的未开发潜力。我们开始探索这些领域，但很快就遇到了阻碍我们进展的问题。

¥Supporting multi-language sites in MkDocs is the most requested feature on our discussion board and in conversations with users, yet it presents significant challenges, as MkDocs does not natively support it. The same applies to versioning, which also involves synchronisation of multi-project builds. While the MkDocs ecosystem has developed various plugins and tools to address these issues, there is still substantial untapped potential. We began exploring these areas but quickly encountered problems that hindered our progress.

您可能知道，我们最初的工作涉及项目插件，该插件旨在扩展 MkDocs，以增加对多项目环境的支持，为支持多语言站点和版本控制奠定坚实的基础。遗憾的是，由于 MkDocs 的内部架构和设计限制，我们遇到了重大挑战，我们正在积极努力解决这些问题。5

¥As you may know, our initial effort involved the projects plugin that aims to extend MkDocs to add support for multi-project environments as a solid foundation to support multi-language sites and versioning. Unfortunately, we encountered significant challenges due to MkDocs' internal architecture and design constraints, which we're working actively on resolving.5

目标 - 通过提供集成多个文档项目的无缝方法，将文档扩展到任何规模或团队结构，无论它们涉及不同的语言、版本还是整体工作的不同部分。

¥ Goal – Enable scaling documentation to any size or team structure by offering seamless methods for integrating multiple documentation projects, whether they involve different languages, versions, or distinct sections of an overall body of work.

因此，我们正在开发一种新方法，以提供更全面、更强大的多语言支持和版本控制解决方案。这种新方法也与搜索等相关功能相交叉，因为我们的许多用户对联合搜索功能感兴趣，该功能可以将来自多个文档站点的结果整合到一个统一的搜索界面中。克服这一挑战是我们在发布新搜索系统之前需要解决的主要障碍之一。

¥As a result, we are developing a new approach to offer a more comprehensive and robust solution for both multi-language support and versioning. This new approach also intersects with adjacent functionalities like search, as many of our users are interested in federated search capabilities that combine results from multiple documentation sites into a unified search interface. Overcoming this challenge is one of the major hurdles we need to address before releasing the new search system.

编辑与协作

¥Editing and collaboration

我们曾考虑开发一个实时编辑器来解决 MkDocs在大型项目中的性能问题，这些问题大多数情况下源于不使用缓存的计算密集型插件。基于Pyodide （在浏览器中运行 Python）的概念验证引起了用户的极大兴趣，并促使许多组织和个人分享他们的协作工作流程以征求反馈。遗憾的是，实现这个实时编辑器被证明非常具有挑战性，因为它需要重建 MkDocs 的大部分内容。6 在停止这种方法的工作后，我们在多项目支持方面取得的进展使我们重新相信，我们最终可以解决过去几年多次报告的编辑体验缓慢的问题。7

¥We had considered developing a live editor in response to MkDocs' performance issues with large projects, which in most cases stem from compute-intensive plugins that don't employ caching. A proof of concept based on Pyodide (= running Python in the browser) generated significant interest among users and prompted many organizations and individuals to share their collaborative workflows for feedback. Sadly, implementing this live editor proved to be very challenging, as it would require rebuilding substantial parts of MkDocs.6 After discontinuing work on this approach, our progress with multi-project support has renewed our belief that we can finally solve the sluggish editing experience that was reported several times over the last years.7

这引出了协作，这最初并非我们的优先事项。然而，在整个2024年，我们与各个组织和热门开源项目的维护者进行了沟通，发现他们经常要求增强协作功能。许多用户表示需要能够允许非技术团队成员对文档提出建议并进行修改的功能。我们由衷地感谢这些反馈，因为它来得正是时候。我们认识到需要简化跟踪和讨论变更的过程，并促进主动贡献。

¥This brings us to collaboration, which wasn't initially on our list of priorities. However, throughout 2024, conversations with various organizations and maintainers of popular Open Source projects highlighted a frequent request for enhanced collaboration features. Many users expressed a need for capabilities that would allow non-technical team members to suggest and make changes to the documentation. We're genuinely grateful for this feedback, as it has come at a pivotal time. We recognize the need to streamline tracking and discussing changes, as well as to facilitate drive-by contributions.

目标——每个人，无论其技术水平如何，都可以轻松地处理和改进文档，并为不断增长的知识库做出贡献。9

¥ Goal – Everyone, regardless of their technical skill level, can easily work on and improve the documentation and contribute to a growing corpus of knowledge.9

这种对协作的关注与企业知识管理方式相契合。在大型组织中，文档通常存在于信息孤岛中——分散却又至关重要的信息存储库。我们深知，需要将这些分散的信息来源统一成一个连贯的知识体系，同时保持去中心化的所有权。这也与我们之前概述的多项目支持工作以及在多个项目之间实现联合搜索的新搜索系统完美契合。

¥This focus on collaboration aligns with how knowledge is managed in enterprises. In large organizations, documentation often exists in information silos — decentralized yet essential repositories of information. We understand the need to be able to unify these disparate sources into a coherent body of knowledge while preserving decentralized ownership. This also nicely aligns with our previously outlined work on multi-project support, as well as the new search system to implement federated search among multiple projects.

大型语言模型（LLM）

¥Large Language Models (LLMs)

大约一年前，我们在文档网站上推出了一个实验性的聊天机器人。它很快就成为了最受期待的功能之一，用户纷纷要求在自己的网站上部署类似的功能，这凸显了人们对交互式文档工具日益增长的需求。然而，我们发现，在现有的众多聊天解决方案中再添加一个，并在 ChatGPT 的基础上再构建一个薄薄的包装器，这种做法是毫无意义的。

¥Almost a year ago, we introduced an experimental chatbot on our documentation site. It quickly became one of the most anticipated features, with users requesting the ability to deploy similar functionality on their own sites, underscoring the growing demand for interactive documentation tools. However, we found that adding to the myriad of existing chat solutions and simply building another thin wrapper on top of ChatGPT is nonsense.

目标——我们设想创建一个统一的界面，无缝集成高级搜索、聊天和摘要功能，提供交互式文档体验。

¥ Goal – We're envisioning creating a unified interface that seamlessly integrates advanced search, chat, and summarization features, providing an interactive documentation experience.

随着我们深入研究这个雄心勃勃的项目，我们从用户反馈中获得了宝贵的见解。用户开始用他们的母语与聊天机器人互动，考虑到我们的文档是英文的，这出乎我们的意料。令人惊讶的是（对于那些常年攻读法学硕士的人来说，这显而易见），聊天机器人竟然用同样的语言回复。法学硕士的这种能力是这些机器学习模型真正令人兴奋的特性之一，因为它有可能提高文档的可访问性。然而，尽管我们采用了最先进的 RAG 方法，但结果却好坏参半，偶尔还会出现幻觉。

¥As we delved into this ambitious project, we gained valuable insights from user feedback. Users began interacting with the chatbot in their native languages, an outcome we hadn't anticipated given that our documentation is in English. Remarkably (or obviously to those that work on LLMs year round), the chatbot responded in the same language. This ability of LLMs is one of the genuinely exciting features of these machine learning models as it has the potential to improve the accessibility of the documentation. However, while we employed state-of-the-art RAG methodologies, the results were mixed, and occasional hallucinations surfaced.

这些经验促使我们优先提升搜索功能，然后再集成基于 LLM 的功能。从零开始构建搜索引擎本身就已经是一项艰巨的工作，在没有坚实的搜索基础的情况下增加复杂性为时过早。通过重新架构我们的搜索功能，我们的目标是创建一个强大的平台，无缝支持高级信息检索，并提供统一的交互式文档体验。

¥These experiences led us to prioritize enhancing our search capabilities before integrating LLM-based features. Building a search engine from scratch was already a substantial effort, and adding more complexity without a solid search foundation would be premature. By rearchitecting our search functionalities, we aim to create a robust platform that will seamlessly support advanced information retrieval and deliver a cohesive interactive documentation experience.

团队、透明度和成长

¥Team, transparency, and growth

在我们应对挑战、探索该项目机遇的同时，我们认为有必要展示我们如何为项目的持续发展和成功奠定坚实的基础。请将此视为概述，而非正式的路线图——我们的详细计划正在制定中。我们重点突出的目标代表了我们力求解决的最具影响力的领域。

¥While we navigate the challenges and explore the opportunities of this project, we consider it essential to demonstrate how we're building a solid foundation for its continued growth and success. Please consider this an overview rather than a formal roadmap — our detailed plans are in the works. The goals we've highlighted represent the most impactful areas we aim to address.

感谢赞助商的慷慨支持，我们很荣幸能够组建一支能够投入大量时间和专业知识的团队来推进这项工作。这支新团队使我们能够更深入地进行核心开发，同时更全面地与用户社区互动。特别感谢@kamilkrzyskow ，他是我们宝贵的社区专家之一，在支持用户和促进平台讨论方面发挥了至关重要的作用。

¥Thanks to the generous support from our sponsors, we're fortunate to be assembling a team capable of dedicating significant time and expertise to this endeavor. This newfound capacity allows us to delve deeper into core development while also engaging more comprehensively with our user community. A special mention goes to @kamilkrzyskow, one of our invaluable community experts, who has been essential in supporting users and fostering discussions on our platform.

在团队的支持下， @squidfunk可以专注于开发的核心，同时我们也开始投入用户研究。这项工作有助于我们了解组织和个人如何与我们的工具互动，并根据与用户和公司进行大量对话的真实反馈来指导项目的未来方向。

¥With the team's support, @squidfunk can concentrate on the heart of development, while we have begun investing in user research. This effort is helping us understand how organizations and individuals interact with our tools, guiding the project's future direction based on real feedback from numerous conversations with users and companies.

为了进一步扩大团队规模，我们致力于提升透明度和沟通能力。之前由于时间限制，我们的工作通常都在幕后进行，但现在我们专注于提升流程的开放性，以更好地吸引新的贡献者。通过这种协作方式，我们旨在增强工具的兼容性，并确保其能够满足社区不断变化的需求。

¥Looking to expand our team further, we are committed to improving transparency and communication. Our previous work often happened behind the scenes due to time constraints, but we're now focused on making our processes more open and inviting for new contributors. By embracing this collaborative approach, we aim to enhance our tools and ensure they meet the evolving needs of our community.

我们的未来

¥What's ahead of us

展望未来，我们现在正在奠定的一些基础对于即将出现的激动人心的发展至关重要。我们讨论过的许多举措都代表着基础性工作，将为更具雄心和创新性的功能奠定基础。一旦这些核心要素到位，我们将提供一系列符合我们愿景和目标的激动人心的新功能。

¥As we look into the future, some of the groundwork we're laying now is crucial for the exciting developments on the horizon. Many of the initiatives we've discussed represent foundational work that will set the stage for much more ambitious and innovative features. Once these core elements are in place, we'll deliver a range of exciting new functionalities that align with our vision and goals.

在接下来的几个月里，我们将分享更多关于我们计划的细节，以及它们将如何帮助我们实现总体目标。虽然增长和创新是我们计划的重中之重，但我们想向大家保证，我们的核心价值观将保持不变。我们致力于维护迄今为止指导我们的原则，确保我们的增长既健康又持续：

¥In the coming months, we'll be sharing more details about our plans and how they will contribute to our overarching objectives. While growth and innovation are at the forefront of our plans, we want to assure you that our core values remain unchanged. We are committed to maintaining the principles that have guided us thus far, ensuring that our growth is both healthy and consistent:

  • 针对近期行业趋势，许多公司正在逐渐远离开源的核心思想，而我们则加倍致力于开源，因为我们相信这是我们工作价值主张和文档即代码方法的核心。

  • 我们的有机增长方法是这一战略的一部分，因为它使我们独立于单个资金来源和提供投资回报的压力，而这导致许多其他项目背离了开源原则。

  • 同样，社区对核心框架丰富适配生态系统的需求也驱动着我们。可扩展性和模块化是实现这一目标的关键，我们正努力通过提供清晰的接口来提升开发者体验。

敬请关注我们的最新动态，我们将持续推进，探索新的可能性。我们对未来充满期待，期待在前进的道路上与您分享更多精彩。

¥Against recent industry trends with companies moving away from core ideas of Open Source, we are doubling down on our commitment to Open Source because we believe it's at the heart of the value proposition of our work and the docs as code approach.

马丁、亚历克斯和凯西

¥Our organic approach to growth is part of this strategy as it keeps us independent of individual funding sources and pressures to provide a return on investment, which is what causes many other projects to turn away from the principles of Open Source.

  1. 我们收集了来自企业和其他开源维护者的宝贵反馈，结果显示实际数字甚至更高。许多组织在私有基础设施（例如 GitLab 等自托管平台）中利用该框架进行内部知识管理。这表明 Material for MkDocs 的真正影响力远远超出了公开可见的范围。↩

  2. Material for MkDocs内置的插件完美地诠释了这一原则，它们相互补充，可以组合使用，构建复杂的流程。这种模块化设计允许用户选择所需的功能，确保框架保持轻量级和灵活性。例如，隐私插件可以与优化插件协同工作，以便外部资源可以与其他文档一样通过相同的优化流程。这意味着您可以在代码库之外存储和编辑未优化的文件，并让这两个插件自动为您构建一个优化的网站。↩

  3. 在BM25中提升文档权重可能会带来挑战，尤其是在文档库不断变化的情况下。相关性是根据词频和整个语料库中词的重要性计算的。提升文档权重涉及调整其权重，使其在搜索结果中更加突出。随着新文档的添加或现有文档的修改，词频及其重要性的整体分布可能会发生变化。这种重新校准可能会降低提升的有效性，使得在不断变化的数据集中保持一致的排名变得更加困难。本质上，提升后的文档可能无法像预期的那样保持突出或相关，从而导致搜索结果的不平衡和可扩展性问题。↩

  4. Lunr.js 使用 JavaScript 对象来索引和管理搜索数据，由于 JavaScript 引擎处理对象操作的方式，这会导致效率低下。JavaScript 引擎使用内联缓存和对象形状优化等技术来优化性能。然而，这些优化依赖于可预测且一致的对象结构。Lunr.js 索引的动态特性（文档可以具有不同的结构）阻碍了引擎有效地应用这些优化。这意味着，虽然 JavaScript 引擎可以针对固定的、可预测的对象结构进行优化，但它们难以应对 Lunr.js 索引的多态性和流动性，从而导致数据量增长时出现性能问题。↩

  5. 在开发项目插件时，我们最初取得了良好的进展，包括添加对嵌套项目的支持并允许使用树结构，其中子项目可以进一步包含子项目。然而，我们很快遇到了困难，特别是跨项目导航。为了说明，假设每个项目都可以链接到任何其他项目，这使得处理这些互连变得复杂，特别是在处理循环依赖时 - 例如项目 A 链接到项目 B，反之亦然。在 MkDocs 中实现多项目支持尤其具有挑战性，因为缺乏官方的编程 API，这使得扩展其功能的努力变得复杂。此外，在构建项目之前解决导航问题对于确保正确的互连至关重要。这些挑战结合在一起，使得项目插件的开发成为一项复杂的工作。↩

  6. 我们的概念验证支持了 Material for MkDocs 的部分功能，但并未涵盖所有功能。例如，集成图标支持或文档间链接功能需要重新实现 MkDocs 的部分功能，以绕过全面重建——这显然是我们想要避免的。此外，某些链接（例如从架构生成的博客文章链接）不仅会被翻译，还会动态计算，这意味着无法通过将.md扩展名替换为.html来推断它们。↩

  7. 在我们再次向 MkDocs 的维护人员8提出了这个问题之后，维护人员在 2024 年中期发生了变化，我们开始从头开始重写，旨在通过仅渲染当前正在构建的页面来解决重新加载缓慢的问题。目前还不清楚这次重写将如何与现有插件的要求相结合。复杂的插件（如mkdocstrings ，或我们的内置博客和标签插件）需要协调构建所有页面，以准确解析页面之间以及与计算资源之间的链接，如果不构建整个项目，就无法确定这一点。更新：新的维护者现在公开表示，他正在开发一个不需要或支持插件的新版本的 MkDocs ，并提到它将同样能够通过模板、主题和样式提供定制，他在8 月 1 日的团队电话中也向我们和其他几个用户提到了这一点。在这次电话会议中，我们多次就这将如何影响生态系统提出反对意见，但无济于事。没有提供插件支持的意向或路线图。这项开发与我们的目标是一致的，即通过模块化的方式，让用户和组织能够根据自身需求调整核心框架。我们正在努力解决这个问题，并将为社区提供前进的方向。↩

  8. 之前提出的问题包括#2418 、 #2384和#1900。↩

  9. 我们正在积极调整未来的开发工作以解决这一问题，并认识到这是一个需要改进的关键领域。虽然我们无法立即实现这一目标，但我们致力于在工作中将这一愿景变为现实。↩