Request Description

In order to edit the wiki, one must be given write permissions. However this enables one to also push to the code repository which is undesirable.

Current Solution(s):

• Create a separate wiki: The wiki will be housed on its own repository with an action that auto-syncs the wiki to here.
  
  Problems with it: The secret token granted to the action can still be misused to write to the code repository. Also Github Wiki lies about conflicts despite there being no conflict, so the action must constantly force-push.
  
  Advantages: Github Wiki ignores folders so you can now at least organize files despite it being displayed otherwise.

Other solutions may be proposed here.

Is it possible to PR changes to the wiki? That's not how wikipedia works but it might be good enough for documentation updates?

The solution may just be to use an external wiki service, and have it source the content from a GitHub repository. Even if we managed to get access controls working with GitHub's Wiki (which would be a huge hack), it's still a very poor solution in terms of actual rendering and organization capability.

There are various wiki solutions that run on GitHub pages that simply render a static page in an Action when you PR (or commit) new changes. Jekyll for example has built-in support https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll and is used by various well known projects.

Is it possible to PR changes to the wiki? That's not how wikipedia works but it might be good enough for documentation updates?

No.

There are various wiki solutions that run on GitHub pages that simply render a static page in an Action when you PR (or commit) new changes. Jekyll for example has built-in support https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll and is used by various well known projects.

That is probably the better solution by far, or using an external service as Jellysquid mentioned.

I use GitBook which has a free personal plan and an paid-like OSS plan. It works by having a separate repo where people can PR edits into.

Its own UI also allows some sort of "teams", but I prefer GitHub's web interface anyway.

I use GitBook which has a free personal plan and an paid-like OSS plan. It works by having a separate repo where people can PR edits into.

Its own UI also allows some sort of "teams", but I prefer GitHub's web interface anyway.

We love GitBook at Switchroot. I can HIGHLY recommend it. You can edit directly from github/gitlab by pushing to the repo or edit from the gitbook UI. We have the "pro like" OSS community plan (free from gitbook because we are an OSS qualifying project). Here is our page so you can have a look https://wiki.switchroot.org/wiki/ and the gitlab repo that backs ours https://gitlab.com/switchroot/infra/wiki . Individual users can be members of the gitbook team and have various roles https://docs.gitbook.com/account-management/member-management/roles . For example, in the sodium gitbook, you might want to have "untrusted" users be able to create gitbook change requests but not be able to merge them, that would be an editor role.

Previously, before GitBook, we were using a self hosted instance of wikijs (2.x) but accidentally deleted the entire wiki contents due to a failed docker volume. wikijs doesn't have any git integration or any history saving, so when it is gone it is gone. That is why I would suggest against using it (in addition to the burden of having to host it yourself).

GitBook might be more than is needed for a "simple" (in comparison) project like sodium but its an option I would definitely look into.