Skip to content

Commit 86d3729

Browse files
katharinalisalinkatharinalisalin
authored
Created new and better Insiders documentation (#7210)
* Updated Insiders documentation * Updated Insiders documentation
1 parent 1b346eb commit 86d3729

14 files changed

+1685
-1120
lines changed

‎docs/insiders/access-management.md

+204
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Access management
2+
3+
The Material for MkDocs Insiders repository is a private repository hosted on
4+
GitHub and access is, therefore, managed through GitHub. This section covers
5+
everything you need to know in order to gain access to the private Material for
6+
MkDocs Insiders repository.
7+
8+
## How to get access
9+
10+
As the private Material for MkDocs Insiders repository is hosted on GitHub, you
11+
require a GitHub account to become a sponsor and to gain access. After
12+
sponsoring us on one of our [sponsoring tiers] starting at [$15 a month],
13+
you'll get access to the private Insiders repository.
14+
15+
Please note that the process of gaining access is only partially automatable due
16+
to technical reasons. Depending on the type of account you've used to become a
17+
sponsor, we might need more information from you before we can grant access.
18+
19+
[$15 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
20+
[sponsoring tiers]: sponsoring-tiers.md
21+
22+
### Individuals
23+
24+
If you sponsor using a [personal account], you will receive an invitation link
25+
via email to the private Material for MkDocs Insiders repository immediately
26+
after initiating your sponsorship. This link is [valid for seven days]. Once you
27+
accept the invitation, you'll be ready to [get started].
28+
29+
If the link expired, please contact us at [email protected] and we'll
30+
send you a new one.
31+
32+
[personal account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
33+
[valid for seven days]: #expired-invitations
34+
[get started]: getting-started.md
35+
36+
### Organizations
37+
38+
When sponsoring using an [organization account], GitHub will not send an
39+
automated invitation via email to access the private Material for MkDocs Insiders
40+
repository. Due to [GitHub limitations], granting access to a private repository
41+
for an entire organization is not possible.
42+
43+
Therefore, please contact us at [email protected] with the name of a
44+
[personal account] or the name of a [bot account] that is publicly or privately
45+
listed as an owner of your GitHub organization after you received a confirmation
46+
that your sponsorship was initiated.
47+
48+
We will add this designated account as a collaborator, and once the invitation
49+
is [accepted within seven days], your organization will be all set to [get
50+
started].
51+
52+
[organization account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
53+
[GitHub limitations]: #collaborators
54+
[bot account]: #bot-account
55+
[accepted within seven days]: #expired-invitations
56+
57+
### Enterprises
58+
59+
If you would like to sponsor us using an [enterprise account], we recommend
60+
using a [personal account] or a [bot account] to initiate the sponsorship and
61+
access the private Material for MkDocs Insiders repository using this account.
62+
63+
[enterprise account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#enterprise-accounts
64+
65+
## Restrictions
66+
67+
GitHub sets limitations beyond our control, which is why we require further
68+
information regarding [collaborators] of private repositories and [matching] of
69+
GitHub accounts.
70+
71+
[collaborators]: #collaborators
72+
[matching]: #matching
73+
74+
### Collaborators
75+
76+
GitHub policy limits access to [private repositories] to [personal accounts]
77+
only, which is why it is currently not possible for us to add [organization
78+
accounts] to the Material for MkDocs Insiders repository – a private
79+
repository.
80+
81+
As much as we would love to give each member of your organization access, it's
82+
simply not feasible for us to add each member account, which is why every
83+
[sponsoring tier] is limited to one seat. However, you can use a [bot account]
84+
to work around this limitation.
85+
86+
[private repositories]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository
87+
[personal accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
88+
[organization accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
89+
[sponsoring tier]: sponsoring-tiers.md
90+
[team management]: #team-management
91+
92+
### Matching
93+
94+
Due to privacy reasons, GitHub does not allow email addresses to be matched with
95+
GitHub accounts. When requesting access via email at [email protected],
96+
it's necessary to provide us with the name of a [personal account].
97+
98+
## Bot account
99+
100+
Given that only personal accounts can be listed as collaborators on
101+
[private repositories], ensuring access for an entire organization requires
102+
coordination through individuals. Changes within the team could lead to losing
103+
access to the entire organization.
104+
105+
To avoid this, you have the option to create a bot account, which is
106+
[a new personal account] that does not belong to a specific individual but is
107+
publicly or privately listed as the owner of the GitHub organization
108+
109+
Using a bot account for access management and initiating your [public] or
110+
[private] sponsorship through it also allows for better attribution of
111+
sponsorship costs, allowing you to manage access and payment for all
112+
sponsorships through a single account, and is thus recommended.
113+
114+
[a new personal account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
115+
[public]: privacy.md/#public-sponsors
116+
[private]: privacy.md/#private-sponsors
117+
118+
## Expired invitations
119+
120+
The invitation to the private Material for MkDocs is valid for seven days, a
121+
limitation imposed by GitHub. If invitations are not accepted within this
122+
period, you'll need to contact us via mail at [email protected], and we
123+
will re-issue the invitation immediately.
124+
125+
## Team management
126+
127+
If you are using Material for MkDocs Insiders as an [individual] and don't
128+
collaborate with other users, [forking] the private repository is not necessary.
129+
However, when working with a team, it is not possible to simply share your
130+
collaborator status with other accounts. Therefore, in order to work in a team,
131+
the account with access to Insiders can [fork], [clone], or [mirror] the private
132+
Material for MkDocs Insiders repository to an organization, providing a pathway
133+
for team collaboration.
134+
135+
[fork]: #forking
136+
[clone]: #cloning
137+
[mirror]: #mirroring
138+
[individual]: #individuals
139+
140+
### Outside collaborators
141+
142+
When working with outside collaborators, you should know that the Insiders
143+
edition is compatible with the community edition. All new features and
144+
configuration options are backward-compatible or implemented behind feature
145+
flags. Most Insiders features enhance the overall experience, e.g., by creating
146+
better social cards or instant previews. While these features add value for your
147+
site's users, they are most certainly not necessary for previewing your site.
148+
149+
This means that outside collaborators can build the documentation locally with
150+
the community edition, and when they push their changes, your CI pipeline will
151+
build it with Insiders. When using [built-in plugins] exclusive to Insiders, we
152+
recommend using the [group] plugin.
153+
154+
See the [getting started guide] for more information.
155+
[getting started guide]: getting-started.md
156+
[built-in plugins]: index.md#built-in-plugins
157+
[group]: ../plugins/group.md
158+
159+
### Forking
160+
161+
[Forking] a repository creates a copy of the repository that allows for
162+
independent development while maintaining a link to the original repository
163+
for updates.
164+
165+
[forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
166+
167+
### Cloning
168+
169+
[Cloning] a repository copies the repository to your local machine or codespace,
170+
facilitating offline work and content management. You can, of course, also
171+
[clone a private fork].
172+
173+
[cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
174+
[clone a private fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository
175+
176+
### Mirroring
177+
178+
[Mirroring] a repository creates an identical copy, ensuring you have the
179+
flexibility to host and work with the repository [in other environments] besides
180+
GitHub. This is a particularly useful strategy for organizations hosting their
181+
repositories in a private environment outside of GitHub.
182+
183+
[mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
184+
[in other environments]: #github-alternatives
185+
186+
## GitHub alternatives
187+
188+
Material for MkDocs Insiders is designed to be compatible with various
189+
repository hosting platforms, including GitLab. The key requirement is still a
190+
GitHub account, as we use GitHub Sponsors for transactions and GitHub to manage access to the private Insiders repository.
191+
192+
Once you've become a sponsor and secured access to the private Insiders
193+
repository via an individual GitHub account, you can [mirror the repository in
194+
another location]. This mirroring process not only allows for easy integration
195+
into your existing workflow but also ensures that your projects stay up-to-date
196+
with the latest features and improvements of Insiders.
197+
198+
Our discussion board is a valuable resource for any questions about integrating
199+
Material for MkDocs Insiders into your projects. It offers a space to connect
200+
with others who may have similar requirements and setups, as well as to
201+
exchange tips and explore solutions together.
202+
203+
[mirror the repository in another location]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository-in-another-location
204+
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions

0 commit comments

Comments
 (0)