Using Insiders for an open source project.

[UltraInstinct05]

If a user is planning to use Insiders for an open source project (where s(he) expects other users to also contribute), is that covered under the terms & conditions of using Insiders ? In other words, I might be a sponsor, but open source contributors to my project may not be sponsors, so are they allowed to also use Insiders while contributing ? If so, any guidelines/things to keep in mind ?

Thanks ! :)

[squidfunk]

Of course! Several Open Source projects already use Insiders, e.g. FastAPI. The terms are the same for Open Source and commercial projects – you're not allowed to release the source code of Insiders, because this would invalidate the whole funding model and will lead to me not being able to work on this project anymore, thus everybody loses. Also, you shouldn't share the source code with outside contributors. As long as that's covered, it's good.

In order to support outside contributions, you can use Insiders in a GitHub Action to build your documentation project. This means that you won't have to share your access, but users are still able to contribute. Also, they can use the non-Insiders version locally to preview changes, and when changes are pushed, the documentation is built and released with Insiders.

That's exactly how FastAPI and also Material for MkDocs do it.

[UltraInstinct05]

What about situations where the contribution does deal with insiders only feature ? Also if the contributors use non insiders, while the project is built & deployed with insiders, won't there potentially be compatibility issues ? How compatible is insiders with non insiders ?

P.S: Apologies, if the constant questions are a bother (I am just trying to assess how best to use insiders for my project while following the terms & conditions for use).

[squidfunk]

No worries. However, I invite you to study the Insiders documentation, which should answer a lot of your questions, e.g. on compatibility. Insiders is almost completely downward compatible. The only thing that is problematic is the Insiders plugins not being available, which can be mitigated by using configuration inheritance.

[squidfunk]

As a general note: when I make changes to the documentation, I always do them on the non-Insiders version, and then let Insiders deploy the "sugared" version via GitHub Actions. Thus, I'm following the same pattern

[UltraInstinct05]

Also, they can use the non-Insiders version locally to preview changes,

I am not exactly sure how this works if the site uses insiders features, since they (the one who contributes) are using non insiders to preview, so either the site will be broken for them or it won't render properly.

[squidfunk]

It's not broken, it's just that some things are not as fancy as with Insiders, or features are just not enabled, like cookie consent, social cards, annotations, etc. The documentation will work with the non-Insiders version as long as you split out the plugin configuration into a dedicated mkdocs.yml as denoted in the link to the documentation I shared in my previous comment.