Skip to content

过去、现在和未来

¥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 年添加的所有功能，并展望了 2022 年将会推出的功能。此外，它还提供了有关该项目历史的一些背景信息。

¥This article showcases all features that were added in 2021 and gives an outlook on what's going to drop in 2022. Additionally, it provides some context on the history of the project.

一点历史

¥A little history

2015 年，尽管我已经在这个行业工作了 10 年，但我对开源仍然很陌生。我想发布我最新的开源项目protobluff ，这是一个零拷贝的 C 语言协议缓冲区实现，是我之前在创业公司创建的一部分。由于这个项目相当复杂，我很快意识到我需要一份完善的用户文档。

¥In 2015, albeit 10 years in the industry, I was still quite new in Open Source. I wanted to release my latest Open Source project protobluff, a zero-copy Protocol Buffers implementation for C, which I've created as part of my former startup. As the project has a significant degree of complexity, I quickly realized that I was in need of good user documentation.

在评估了各种静态站点生成器，尤其是 Hugo、Sphinx 和 MkDocs 之后，我很快就认定 MkDocs 是个不错的选择，因为它专门针对技术项目文档，而且易于使用。可惜的是，所有可用的主题看起来都有些过时，考虑到我是一个非常注重视觉效果的人，我实在无法说服自己就此罢休。

¥After evaluating static site generators in general and Hugo, Sphinx and MkDocs in particular, I quickly decided that MkDocs seemed a good choice, as it was specifically aimed at technical project documentation and easy to use. Unfortunately, all of the available themes looked dated and given that I'm a very visual person, I just couldn't convince myself to call it a day.

我必须建立一个主题。

¥I had to build a theme.

几个月后，在 2016 年 2 月，我发布了 Material for MkDocs 的第一个版本（以及我最初想要发布的项目protobluff ），它看起来像这样：

¥Months later, in February 2016, I released the first version of Material for MkDocs (and with it, protobluff, the project I wanted to release in the first place), and it looked like this:

Material for MkDocs 0.1.0

它已经完全响应式了，总体来说还不错，但几乎无法自定义，只能更改徽标。除此之外，它没有任何选项：没有颜色或导航选项，没有即时加载等等。搜索功能非常简陋，仅支持章节标题：

¥It was already fully responsive and overall, well, quite okayish, but barely customizable, as only the logo could be changed. Beyond that, it had no options: No color or navigation options, no instant loading, etc. The search was very rudimentary and only supported section titles:

Material for MkDocs 0.1.0 Search

值得一提的是，目前我已经为protobluff构建了 Material for MkDocs，而 protobluff 正是我真正关心的项目。近六年过去了，protobluff 已经无人知晓，但这个小小的副业项目却蓬勃发展。如果在那个年代，你告诉我像 AWS、微软和 CERN 这样的大型组织，以及像 FastAPI 和 Kubernetes 这样非常流行的开源项目将来都会使用这个项目——我肯定会说你疯了。

¥It's important to know that at this point in time I've built Material for MkDocs for protobluff, the project I was really caring about. Almost 6 years later, nobody knows protobluff, but this little side project has taken off. If back in those days, you would've told me big organizations like AWS, Microsoft and CERN, as well as extremely popular Open Source projects like FastAPI and Kubernetes will be using this project in the future – I would've declared you insane.

我仍然对这个项目的成功感到相当惊讶，因为我以为主题已经非常丰富，而且基本上已经解决了。主题本身没有什么荣耀，也没有什么值得获得的星星（记住，我是开源领域的新手，所以我优化的指标就是这个），因为有成千上万个选项。然而，随着时间的推移，我了解到执行至关重要：尽管 Material for MkDocs 解决了一个存在成千上万个解决方案的问题，但它在一个特定的领域表现出色，这个领域就是所谓的技术项目文档。

¥I still find the success of this project quite surprising, as I thought that themes exist in abundance and are very much a solved problem. There's no glory in themes, no stars to earn (remember that I was new in Open Source, so this was the metric I was optimizing for), as there are thousands and thousands of options. However, as the years progressed, I learned that execution matters: although Material for MkDocs solves a problem for which thousands of solutions exist, it excels in a specific niche, and that niche is to be known as technical project documentation.

如今，这个项目不仅广受欢迎，还得到了近 300 名个人和组织的资助，每年的预算超过 5 万美元。这让我有足够的时间开发新功能、修复错误、提升稳定性、进行问题分类并提供常规支持。但我仍然觉得这像是一个梦想，因为开源项目融资失败的例子有很多，而且有人会告诉你：不要做开源，你就是白干。

¥Today, this project is not only popular but funded by almost 300 individuals and organizations, resulting in a yearly budget of more than $50,000. This allows me to set aside enough time for the development of new features, bug fixing, stability improvement, issue triage and general support and still feels like a dream to me, as there are many failed stories of Open Source funding and people telling you: don't do Open Source, you'll be working for free.

毕竟，在 2021 年，开源的可持续发展是可能的。

¥Making Open Source sustainable is, after all, possible in 2021.

2021年数据

¥2021 in numbers

2021 年是令人兴奋的一年，因为该项目取得了显着增长。

¥2021 was an exciting year, as the project has seen significant growth.

2021年，官方文献访问量达16.6万人次，页面浏览量达160万次，较2020年增长83%。平均每位访客在网站上停留1.5分钟。手机访问量占比12%，而平板电脑仅占0.6%。访客来自213个国家，几乎覆盖全球。

¥166k people visited the official documentation in 2021, totalling in 1,6m page views which is an increase of 83% when compared to 2020. The average visitor spends 1,5min on the site. While mobile phones make up 12% of visits, tablets only account for 0.6%. Visitors come from as many as 213 countries, which covers almost the whole world.

特征

¥Features

令人振奋的是，2021 年全年，Material for MkDocs 新增了38 个功能——相当于每 9.6 天新增一个功能——这得益于持续改善的资金状况。以下是所有已发布功能的列表（按字母顺序排列），其中一些功能仍作为Insiders 计划的一部分仅供赞助商使用：

¥It's absolutely mind-blowing that 38 new features were added to Material for MkDocs throughout 2021 – that's a new feature every 9,6 days – which was only possible because of the constantly improving funding situation. Following is a list of all features shipped in alphabetical order, some of which are still exclusively available to sponsors as part of Insiders:

此外，今年推送到代码库的1,000 次提交中修复了大量错误。更新日志包含所有修复的列表。此外，我们还投入了大量时间重构代码库，以保持其良好状态。mkdocs mkdocs-material软件包发布了55次，而mkdocs-material-insiders发布了72次。

¥Additionally, a lot of bugs were fixed in the 1,000 commits that were pushed to the repository this year. The changelog includes a list of all fixes. Furthermore, a large amount of time was invested into refactoring the code base to keep it in good shape. While the mkdocs-material package was released 55 times, mkdocs-material-insiders was shipped 72 times.

资金

¥Funding

2021年，每月资助金额从1月初的1,050美元增加到2021年12月27日的4,300多美元，年度预算总额超过5万美元。与去年相比，资助收入增长了617% ——这绝对令人难以置信：

¥In 2021, monthly funding increased from $1,050 in the beginning of January to more than $4,300 (Dec 27, 2021), totaling in a yearly budget of more than $50,000. Compared to last year, revenue from funding has increased by 617% – which is absolutely unbelievable:

Funding

我提供这些数字仅仅是为了履行我对我的优秀赞助商做出的透明度承诺，并表明通过遵循精心设计的发布策略可以使现有的开源项目可持续发展。

¥I'm solely providing these numbers to fulfill the transparency pledge I'm giving to my awesome sponsors, and to show that it's possible to make existing Open Source projects sustainable by following a well-designed release strategy.

您可以在内部人员指南中了解该策略。

¥You can learn about the strategy in the Insiders guide.

2022

¥2022

值此新年伊始，我们可以肯定地说，该项目将继续蓬勃发展，并催生出许多令人惊叹的功能，让技术写作更加舒适灵活。以下是一些将于 2022 年面世的功能摘录：

¥Standing at the verge of the next year, it's safe to say that the project will continue to prosper and evolve, yielding many awesome features that will make technical writing more comfortable and flexible. Here's an excerpt of the features that will see the light of day in 2022:

  • 即时预览：当鼠标悬停在内部链接上时，即时预览会在工具提示中呈现特定的页面部分，从而实现词汇表等功能。此外，我们还将研究进一步改进词汇表功能的支持。

  • 文本注释：作为 2021 年新增代码注释功能的逻辑延续，作者将能够为纯文本添加注释，从而为侧边内容提供绝佳的机会。当然，文本注释的使用将与代码注释一样简单易用。

  • 导航修剪：为了优化大型文档项目，Material for MkDocs 将引入一个名为navigation.prune的新功能标志，这将使具有庞大导航层次结构的文档项目的 HTML 文件明显变小。

  • 导航状态徽章：作为最近添加的导航图标支持的补充，每个页面将具有一个状态，允许使用图标在导航树中标记页面新的或已弃用。自定义状态类型也将受支持。

  • 卡片网格：作为技术写作工具包的又一组成部分，卡片网格允许以网格形式排列内容，这对于概览页面尤其有用。它们允许排列任意内容，包括代码块、警告等。

  • 博客支持：博客支持仍在调查中，预计将成为 2022 年的主要新增功能之一。博客将与编写文档完美结合，允许使用 Material for MkDocs 中提供的所有组件。

此列表并不完整。此外，与 2021 年一样，明年还将添加许多新的小型功能。您可以在 X 上关注 @squidfunk以获取最新信息。

¥Instant previews: instant previews will render a specific page section inside a tooltip when hovering an internal link, which will allow to implement things like glossaries. Further support for improving glossary functionality will also be investigated.

新年快乐！

¥Text annotations: as a logical progression of code annotations which were added in 2021, authors will be able to add annotations to plain text, yielding excellent opportunities for side content. Of course, text annotations will be as easy to use as code annotations.