squidfunk

True, Material for MkDocs doesn't have a working out-of-the-box solution for working code examples, as it's a language-agnostic theme for documentation, but it shouldn't be too difficult to integrate [1].

[1]: https://dev.to/yysun/make-code-run-in-your-docs-4800

Thanks! To those interested in the mechanics of the Insiders monetization strategy, I've talked more about in [1]

[1]: https://news.ycombinator.com/item?id=25884018

Just to clarify: the left-hand sidebar is the navigation, which collapses into the drawer behind the hamburger menu icon on breakpoints below 1220px. The right-hand sidebar is the table of contents which lists all anchor links specific to the page.

> Except, if I refresh the page, now the right hand sidebar goes away for some reason.

That is very weird and not intended. I just tried to reproduce the behavior (macOS, Chrome), but to no avail. If you have the time, it'll be great to have an issue with steps to reproduce (and possibly a screen capture), so we can fix it!

No, it's just a theme for MkDocs [1], a static site generator that has no affiliation with Google. Material for MkDocs only borrows the Material Design philosophy from Google.

[1]: https://www.mkdocs.org/

> On the other end of the spectrum you have tools like MkDocs (or mdbook, docsify, docusaurus, etc.) which are more focused on technical docs in markdown format. These tools put much less emphasis on schema, layout, taxonomy and really try to go from a pile of simple markdown files to a rendered site with as little friction as possible. You typically just lay out files in the filesystem, make simple markdown links between files, and the tool takes care of all the details of building a doc site like layout, rendering, linking, table of contents, and even search.

That's exactly the value proposition of Material for MkDocs. Just throw Markdown at it and tweak it with some configuration, if desired.

> MkDocs strikes a really nice balance in this regard--you basically just write markdown files with simple links and it will figure out the rest. The Material theme here is _very_ slick and one of the best out of the box themes you'll find for any technical docs generator (or even SSG in general) period.

Thanks!

Thanks! I'm glad to hear that. Indeed, a lot of love went into the search and there're still some things that will be improved on the search in the coming months, e.g. more concise search result summaries.

Thanks!

> I think the tablet viewport (aka desktop-not-maximized) could use bit more love

IMHO, layouts for tablet viewports are often quite frankensteiny and hard to get really great. Is there anything in particular you feel could be improved?

> it's strange to include a dark mode slider and not respect my system dark mode setting

Material for MkDocs can do that [1], but I've disabled it for the documentation as I like the actual documentation for this tool to have the what I'd call "canonical" styling.

[1]: https://squidfunk.github.io/mkdocs-material/setup/changing-t...

Author here, AMA!

Thanks! That is great to hear. Making writing documentation as frictionless and easy as possible is the primary goal of this project. Happy to welcome you aboard as a sponsor!

I do 99% of the work, but of course I also accept contributions. However, PRs are very rare and are mostly about bugfixes, not new features. Bugfixes are always released as part of the non-Insiders version, of course.

What's probably interesting is to consider the user demographics, about which I learned more in a survey [1] I did last year. Only 8% of my user base would consider themselves Frontend engineers. Given that this is an HTML template with some rather complex CSS/JS, it's not surprising that there are only very few PRs that implement new features. I guess most Frontend engineers go for JavaScript-based solutions like Vuepress or Docusaurus. Material for MkDocs is Python-based.

[1]: https://twitter.com/squidfunk/status/1259832077668810752

It's MIT-licensed, as the original project. I have no interest in legal prosecution. Also, different licensing would make it more complicated for companies.

This is indeed a problem. However, given that you need to pay for a subscription to get access, I consider the risk rather low. The Insiders code is released under the same license (MIT), as I didn't want to make things complicated, so I couldn't even enforce someone publishing it. I have a fair-use policy [1] that (up to now) all users respect.

Yes, the model is far from being perfect, but it allows me to pay at least some of my bills. I'm always curious to learn how to improve it!

[1]: https://squidfunk.github.io/mkdocs-material/insiders/#terms

> What do you do if the sum of the monthly pledges goes down at some point? Will you make those features private again?

Nope, any feature that is released will remain public.

> I guess it's a bit counter-intuitive for me that a one-time release of a feature is tied to a recurring sponsorship level.

In the end, I'm selling early access to new features, that's it. If you need something now, and it's available for sponsors only, you need to subscribe to get access to it. You can always implement it yourself, the project is very hackable and puts a great emphasis on extensibility. The documentation is very thorough, also in respect to customization. However, sometimes, maybe especially for something like technical documentation, you don't want to be fighting browser bugs and edge cases.

Is it greedy if, after investing months or years of work, answering issues, implementing feature requests, you feel like you deserve to be somehow compensated for your work, especially with successful companies using your software, benefiting from it?

The model may be far from being perfect, I'm still learning and adjusting what works and what doesn't, but it feels much better investing my time into this project since I get something back.

Sponsors have access to the private repository (I'm using GitHub's collaborator feature). I have several sponsor tiers and $10 a month or more will get you access to my sponsorware, which means you will be added to the private repository and can use the features immediately. What you're effectively getting is early access, so you can use the features before other users.

The official documentation of my project lists exactly which features are "Insiders only", and which aren't. When the features tied to the funding goal that was hit are merged, everybody can use them. I try to always have sponsors-only features on higher tiers to keep sponsoring attractive.

As I understand, Caleb does it with content and entire projects - I'm doing it with new features for an existing project. Also, I'm doing it fully transparent, disclosing how much I earn with this, which I think is crucial to build the necessary trust relationship.

I also started with GitHub sponsors after reading about Caleb's post about sponsorware in May 2020 and have managed to grow my sponsorships since then to more than $1k a month.

To those who are interested how I did it: I'm the author of Material for MkDocs [1], a popular solution for technical documentation. I created a private fork called "Material for MkDocs Insiders [2]" where all new features landed since then and tied those features to funding goals at $ 500, $ 1,000 etc. The promise is that the moment a funding goal is hit, the features are merged back into the original repo and released for general availability. It works reasonably well so far, better that I would have thought.

My Twitter following is rather small (700), but I'm posting a lot about Material for MkDocs and new features and try to engage the community. I guess if you have a large following like Caleb, you could up the amount in a few months, given that you have something on your hands that users want and solves a problem.

[1]: https://squidfunk.github.io/mkdocs-material/ [2]: https://squidfunk.github.io/mkdocs-material/insiders/

Author of protobluff [1] here - a zero-copy, mostly stack-based implementation for Protocol Buffers in C. Yes, you must scan through the message to find the corresponding tag/value pair you're interested in, but in many cases, it can be fast enough if you're only interested in a few values of a large message. Sure, using a vtable is much faster, as it provides O(1) lookup semantics, but sometimes you may not be able to change to another format without touching the entire stack.

[1]: https://github.com/squidfunk/protobluff

I'm the author of the Material theme which actually has a top bar, a feature called tabs, see http://squidfunk.github.io/mkdocs-material/getting-started/#...