FreeCAD Forum

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?

chennes wrote: ↑Sun May 21, 2023 9:06 pm 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...

gauriimaheshwarii wrote: ↑Sun May 21, 2023 7:28 pm 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.

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

- 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 :)

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

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.

adrianinsaval wrote: ↑Thu May 25, 2023 8:23 pm 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.

yorik wrote: ↑Fri May 26, 2023 9:03 am 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.

Hi

gauriimaheshwarii wrote: ↑Sun May 21, 2023 7:28 pm I thought why not post regular updates of my work here only.

+1

bienvenue au club

mario

Hello everyone!
The project I am working on is upgrading the documentation system of FreeCAD with my mentor @kkremitzki.

For the new documentation of the software, we decided to go with Docusaurus because of several reasons, including the fact that it is git-based and open-source.

Till now, we have worked on the structure of the website, and have defined a layout for it. The first pages of each section and sub-section are made in a new way, though the linked pages still redirect to the current wiki. We are still working on the same, as every page is made manually and there are over a thousand files.
The website is viewable in both light and dark modes.
We are also looking at the possible ways to support multiple languages for the users.
There is still an issue of image sizes to be tackled.
Also, kindly ignore the tutorial tabs on the sidebar.

Reviews from the community are crucial for this project. Here is the link to the work we have done until now.
https://documentation-freecad-docusauru ... docs/intro

Your reviews, suggestions, and ideas are welcome. Please let us know what you think so that we can improve and make it better

You can find the entire code here.

It looks very pleasant. Congrats on your first achievements.
I will be looking forward to information for the translators of the documentation.

ps
As of the middle of last month, the wiki had 1,860 pages that can be translated, There are also a few without translation capabilities.