[GSoC2023] Upgrade the documentation system

[chennes]

I'm very excited to see how this project goes: I am quite fond of Markdown, and I'm very frustrated by the poor search (particularly as it relates to translation) of the current wiki. I've looked a little bit at Docusaurus (which I think you have also seen) and it seemed to hold great promise. I hope you can find a good way to make a seamless transition from the existing documentation to a nicer platform. My understanding of the wiki translation is that it's totally self-contained, right? There's nothing being done on CrowdIn?

[yorik]

My understanding of the wiki translation is that it's totally self-contained, right? There's nothing being done on CrowdIn?

That's right. And of course that's one of the problems. We never know until when our MediaWiki translation plugin will work...

Set up a Wiki in the same repository as a sandbox project to allow the FreeCAD contributors to play around with the documentation and get familiar with the platform.

That's very interesting. The git bla-bla is completely hidden from the user, and there is a sidebar with the page contents. I just tried setting one up too for https://github.com/yorikvanhavre/FreeCAD-NativeIFC . What I like most is that it's basically zero maintenance and platform dependency and extremely portable. I'd be curious to see if it can be ported "as is" to, for example, gitlab or gitea-based platforms like codeberg.org.

[yorik]

Some things that I found out about github wikis:

- You don't use the .md suffix in links.
- You can put files in subfolders, it stays so in the git structure, but you don't use subfolders in links. Ex: a link to subfolder/mypage lokks like this: [my page](mypage)
- We can give wiki write access either to anybody with a github account, or only to collaborators of the FreeCAD repo. This might be annoying as there is no fine-tuning possible (we would want not everybody to be able to write, but also not only people with write permission to the FreeCAD repo)
- The wiki editing interface is the same as the normal markdown edit UI of github. So for editors there is not much advantage in using a wiki over a standard repo

Here is an example of a translated github wiki. Not sure how it was done, though: https://github.com/JustArchiNET/ArchiSteamFarm/wiki

[gauriimaheshwarii]

- May 25, 2023 -

• Tried making the Getting started page in Markdown on GitHub Wiki and Docusaurus.

Check out the Wiki page here.
The Docusaurus website is currently available locally on my system. Attaching link to the screenshots here to show how the 'Getting Started' page looks.

Docusaurus allows viewing in both light and dark modes, and when clicked on 'Edit this page', it redirects to the GitHub repository where the file is located.
Kindly ignore the Tutorial Intro, Basics, and Extras sections on the left and the Blog section on the top.

Your reviews and suggestions are welcome :)

[adrianinsaval]

how do you edit the wiki when using that? does it need to be through a PR on github?

[yorik]

That's nice!
There is a demo version of docusaurus here: https://docusaurus.io/docs/playground
It has also built-in support for crowdin, that's a huge plus.
I would like to see how the git repo associated with a docusaurus site looks like... If it is "portable" enough, that might be a very good solution.

Regarding PRs, if the documentation was on its own repo, we could do even better than on the current wiki: Trusted wiki editors have write permission, and can edit the doc directly, same as they currently do on the wiki, and occasional editors would go through PRs.

[gauriimaheshwarii]

how do you edit the wiki when using that? does it need to be through a PR on github?

Only the collaborators can edit the GitHub wiki. Occasional editors will have to raise a PR.

I would like to see how the git repo associated with a docusaurus site looks like... If it is "portable" enough, that might be a very good solution.

I am still fixing the git repo, was facing some trouble while deploying the website.
Will share an update by Sunday.