Solution (online tool?) to contribute to docs using Material Insiders

[Andre601]

The Insiders program sure is a nice feature to support you (Squidfunk) while gaining early access for specific features to be added into Material for MkDocs.

However, it also has one major downside to it: Limiting collaborations.

The problem is, that if a page uses a currently Insiders-only feature, and a user wants to contribute to the said page will they need to also have Insiders, so as to not encounter a broken preview through mkdocs serve
This means that by using the Insiders version, a software team (or whoever is using Material for MkDocs) is (un)intentionally limiting possible contributions to either people that also have the insiders version, or to changes that do not use Insider-only features.

I recall a tweet from you, Squidfunk, showing some sort of (online) tool to create pages? I cannot find the info however, as it was too long ago and is gone from the Insiders page(?)

Either way, a sort of online tool to preview changes using Insiders features would help a lot in allowing new contributors to help test changes, even when they don't have Insiders.

[squidfunk]

Thanks for suggesting. I've already thought a lot about this and might consider this at some point in the future.

[squidfunk]

Additionally: there are only a handful of features where collaborators are actually limited, as collaboration normally only involves adding or changing content. From the current list of features, only the following are impacted:

• Card grids
• Annotations

All other 24 of the 26 features are not directly related to content, as they are only relevant in the context of the deployed site. Thus, if you need to make sure that collaborators have a fully working version (minus stuff like feedback widget, navigation icons, etc., which are all not essential), you only have to stop using card grids and annotations.

[NicolasMassart]

Note that tools like readthedocs.org (or .com) provide a preview on PRs so if you have your site source code on Github and contributors make changes with PRs, it's possible for them to have a preview rendered without the need to have access to insider.

You can configure Readthedocs to have the preview built with insider (putting token as env variable and setting the requirement.txt file accordingly), so even if you local preview is not exactly the same as the target build, you can still see the exact build in the PR preview before publishing.

If you want to build your own preview without hosting your doc on readthedocs and using their PR preview feature, you can for instance use Github Actions and hosting/building tools like netlify.

[Andre601]

I'm well aware about deploy previews.

I myself have a gh action-based system to make previews: https://github.com/gh-pages-deploy/Deploy-Previews

The point I was making is, that people that want to make changes, preview them locally and don't have insiders can't see changes.
PR previews are a solution, but they are bound to limitations (bandwidth).

[NicolasMassart]

Yes that's true. The issue is that I can't see any way to package the insider version for local use without source code leak...