diff --git a/docs/blog/2021/the-past-present-and-future.md b/docs/blog/2021/the-past-present-and-future.md new file mode 100644 index 000000000..77f239e69 --- /dev/null +++ b/docs/blog/2021/the-past-present-and-future.md @@ -0,0 +1,278 @@ +--- +template: overrides/main.html +description: > + 2021 was an amazing year for this project as we shipped many new awesome + features and made this project sustainable +search: + exclude: true +--- + +# The past, present and future + +__2021 was an amazing year for this project as we shipped many new awesome +features, saw significant user growth and leveraged GitHub Sponsors to make the +project sustainable.__ + + + + [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 + +--- + +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. + +_This article showcases all features that were added in 2021 and gives an +outlook on what's going to drop in 2022. Additionally, it gives some context +on the history of the project._ + + [MkDocs]: https://www.mkdocs.org + +## A little history + +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. + +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. + +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][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][Material for MkDocs 0.1.0 Search] + +It's important to known 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 that 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. + +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_. + +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._ + +Making Open Source sustainable is, after all, possible in 2021. + + [the first version]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Material for MkDocs 0.1.0]: the-past-present-and-future/mkdocs-material-0.1.0.png + [Material for MkDocs 0.1.0 Search]: the-past-present-and-future/mkdocs-material-0.1.0-search.png + [protobluff]: https://github.com/squidfunk/protobluff + +## 2021 in numbers + +2021 was a very interesting year, as the project has seen significant growth. + +__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 + +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]: + +
+ +- [Admonition inline blocks] +- [Advanced search highlighting] +- [Anchor tracking] +- [Back-to-top button] +- [Boosting pages in search] +- [Brand new search plugin] +- [Code annotations] +- [Code annotations: anchor links] +- [Code annotations: strip comments] +- [Code block titles] +- [Code block line anchors] +- [Color palette toggle] +- [Content tabs: improved support] +- [Content tabs: auto-linking] +- Content tabs: animated indicator +- [Cookie consent] +- [Custom admonition icons] +- [Dark mode support for images] +- [Dismissable announcement bar] +- [Excluding content from search] +- Latest release tag +- [Mermaid.js integration] +- [Navigation icons] +- [Stay on page when switching versions] +- [Tags with search integration] +- [Remove generator notice] +- [Rich search previews] +- [Search suggestions] +- [Search highlighting] +- [Search sharing] +- [Section index pages] +- [Site language selection] +- [Social cards] +- [Sticky navigation tabs] +- [Tokenizer with lookahead] +- [Versioning] +- [Version warning] +- [Was this page helpful?] + +
+ +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. + + [Insiders]: ../../insiders/index.md + [Admonition inline blocks]: ../../reference/admonitions.md#inline-blocks + [Advanced search highlighting]: search-better-faster-smaller.md#accurate-highlighting + [Anchor tracking]: ../../setup/setting-up-navigation.md#anchor-tracking + [Back-to-top button]: ../../setup/setting-up-navigation.md#back-to-top-button + [Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting + [Brand new search plugin]: search-better-faster-smaller.md + [Code annotations]: ../../reference/code-blocks.md#adding-annotations + [Code annotations: anchor links]: ../../reference/code-blocks.md#anchor-links + [Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments + [Code block titles]: ../../reference/code-blocks.md#adding-a-title + [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#anchor-linenums + [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle + [Content tabs: improved support]: ../../reference/content-tabs.md + [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs + [Cookie consent]: ../../setup/setting-up-site-analytics.md#cookie-consent + [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons + [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode + [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read + [Excluding content from search]: ../../setup/setting-up-site-search.md#search-exclusion + [Mermaid.js integration]: ../../reference/diagrams.md + [Navigation icons]: ../../reference/index.md#setting-the-page-icon + [Remove generator notice]: ../../setup/setting-up-the-footer.md#generator-notice + [Rich search previews]: search-better-faster-smaller.md#rich-search-previews + [Search suggestions]: ../../setup/setting-up-site-search.md#search-suggestions + [Search highlighting]: ../../setup/setting-up-site-search.md#search-highlighting + [Search sharing]: ../../setup/setting-up-site-search.md#search-sharing + [Section index pages]: ../../setup/setting-up-navigation.md#section-index-pages + [Site language selection]: ../../setup/changing-the-language.md#site-language-selector + [Social cards]: ../../setup/setting-up-social-cards.md + [Stay on page when switching versions]: ../../setup/setting-up-versioning.md#stay-on-page + [Sticky navigation tabs]: ../../setup/setting-up-navigation.md#sticky-navigation-tabs + [Tags with search integration]: ../../setup/setting-up-tags.md + [Tokenizer with lookahead]: search-better-faster-smaller.md#tokenizer-lookahead + [Versioning]: ../../setup/setting-up-versioning.md#versioning + [Version warning]: ../../setup/setting-up-versioning.md#version-warning + [Was this page helpful?]: ../../setup/setting-up-site-analytics.md#was-this-page-helpful + [changelog]: ../../changelog/index.md + +### Funding + +The funding level in 2021 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, __funding has increased by 617%__ – which is +absolutely unbelievable: + +![Funding] + + [Funding]: the-past-present-and-future/funding.png + +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. + + [awesome sponsors]: ../../insiders/index.md#how-to-become-a-sponsor + +## 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 be see the light of day in 2022: + +- __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 opportunies for side content. Of course, text annotations + will be as easy to use as code annotations. + +- __Navigation pruning__: to optimize large documentation projects, Material + for MkDocs will introduce a new feature flag called `navigation.prune` that + will lead to significantly smaller HTML files for documentation projects with + huge navigation hierarchies. + +- __Navigation status badge__: as an addition to the recently added + [navigation icon][Navigation icons] support, a status will be attributable to + each page, allowing to mark a page in the navigation tree with an icon as + :material-alert-decagram: __new__ or :material-trash-can: __deprecated__. + Custom status types will also be supported. + +- __Hover cards__: as a further component in the toolkit of technical writing, + [hover cards] will allow to arrange content in grids, which is especially + useful for overview pages. They will allow to arrange arbitrary content in + grids, including code blocks, admonitions, etc. + +- __Blog support__: blogging support is still [under investigation] and expected + to be one of the major additions in 2022. Blogging will perfectly integrate + with writing documentation, allowing to use all components that are available + in Material for MkDocs. + +This list is incomplete. Additionally, many new smaller features will be added +next year, just as in 2021. You can follow [@squidfunk on Twitter] to stay +updated. + +__Happy new year!__ :tada: + + [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 + [hover cards]: https://github.com/squidfunk/mkdocs-material/issues/3018 + [under investigation]: https://github.com/squidfunk/mkdocs-material/issues/3353 + [@squidfunk on Twitter]: https://twitter.com/squidfunk diff --git a/docs/blog/2021/the-past-present-and-future/funding.png b/docs/blog/2021/the-past-present-and-future/funding.png new file mode 100644 index 000000000..d6cf2193e Binary files /dev/null and b/docs/blog/2021/the-past-present-and-future/funding.png differ diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png b/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png new file mode 100644 index 000000000..22ab1042b Binary files /dev/null and b/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png differ diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png b/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png new file mode 100644 index 000000000..d00c68520 Binary files /dev/null and b/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png differ diff --git a/docs/blog/index.md b/docs/blog/index.md index 80aea595a..095911d2f 100644 --- a/docs/blog/index.md +++ b/docs/blog/index.md @@ -12,6 +12,39 @@ search: # Blog +## [The past, present and future] + +__2021 was an amazing year for this project as we shipped many new awesome +features, saw significant user growth and leveraged GitHub Sponsors to make the +project sustainable.__ + + + + [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 + +--- + +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. + + [:octicons-arrow-right-24: Continue reading][The past, present and future] + + [The past, present and future]: 2021/the-past-present-and-future.md + ## [Excluding content from search] __The latest Insiders release brings three new simple ways to exclude dedicated @@ -29,8 +62,6 @@ control.__ - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - --- Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin, diff --git a/mkdocs.yml b/mkdocs.yml index 6eff977b6..271b659a4 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -212,5 +212,6 @@ nav: - Blog: - blog/index.md - 2021: + - blog/2021/the-past-present-and-future.md - blog/2021/excluding-content-from-search.md - blog/2021/search-better-faster-smaller.md