[Feature Request /Proposal] Moving the Handbook to a new framework.

[senft-research]

This issue is on the back of a discussion that has been had on the discord, and is to ensure proper etiquette before attempting a PR with such a radical change.

The proposal is to move the Developers Handbook to a new framework (most likely Material for MkDocs, the framework used for the blender documentation.

The goal of the initiative would be to have a framework that still is easy to contribute to, whilst also having the QoL features that would improve the on-boarding of developers whom are thinking of becoming contributors.

[hyarion]

Sounds great, we need more people working on onboarding and I think this could help.

[chennes]

Looks good to me -- I've never used Material for MkDocs before, but their site is certainly impressive 😄 . As long as we can still just write the docs in Markdown, I'm happy with anything that improves the end-user experience.

[senft-research]

As an update, it seems like MKDocs is having a bit of internal drama at the moment, so an alternative framework might be for the best.

[hyarion]

It seems like Material for MkDocs has created Zensical as a substitute.

@marcuspollio, did you have any ideas for dev handbook in your website work?

[marcuspollio]

Yeah, sure!
Since early 2025, it is planned for the Developers Handbook to be integrated into the new website as part of the Documentation sections. This is currently WIP and will hopefully be completed by end 2026.

Here is the current `Dev` section structure:

website$ tree content/en/dev/

├── addons
├── cli
├── code
│   ├── cpp
│   ├── formatting
│   ├── python
│   └── review
├── design
│   ├── branding
│   ├── hints
│   ├── naming
│   ├── principles
│   ├── ui-elements
│   ├── ui-glossary
│   ├── ux
│   └── zones
├── docs-writing
├── infra
├── roadmap
├── start
│   ├── clion
│   ├── dependencies
│   └── vscode
├── teams
├── tech
│   ├── app
│   ├── checklist
│   ├── deletion
│   ├── glossary
│   ├── libpack
│   ├── major-release
│   ├── minor-release
│   ├── packages
│   ├── preferences
│   ├── properties
│   ├── python-binding
│   ├── python-stubs
│   ├── references
│   ├── release
│   ├── signing
│   ├── snap
│   ├── src
│   ├── tests
│   └── translations
├── translate
└── web
    ├── cms
    ├── config
    ├── custom
    ├── deploy
    ├── faq
    ├── guidelines
    ├── highlight
    ├── locales
    ├── markdown
    ├── setup
    ├── shortcodes
    └── structure

For features for this particular Dev section (or for other Documentation sections too), there should be some design discussions on the Table of Content, Breadcrumbs and eventual search. Code highlight is already available but could get some tweaks. All other features of the whole website project (shortcodes, Content Management System, render-hooks, and many more) will obviously be available as well.

So if you would like to get involved, please do so in the website repository. Write a comment in this discussion.

Help is needed in particular for:

• Developers Handbook structure review (top-sections, sub-sections, sorting and weights) and tweaks
• Taxonomies, versioning, languages
• Content cleanup
• Features
• Style tweaks

Thank you!

Edit: keep only one useful comment.

[senft-research]

So for context is this integration into the site but with a new framework. Or a hard foot down on "use the websites framework"?

[marcuspollio]

The "new website" is a project I have been leading since almost two years now. It aims to bring together as many of FreeCAD's web components as possible into a unified, coherent, modern, high-performant, scalable architecture that we hope will be more accessible to everyone.
Currently, you have FreeCAD-Homepage, DevelopersHandbook, Blog, Wiki and many more components. All of them work differently (UX, code and maintenance) and almost none of them can work with the others.
So this new unified website is in a sense an iteration on the current components we currently have, but with a new architecture: git-based, Markdown for content, modern vanilla HTML/CSS/JS for theme, CI/CD, integrated Content Management System, etc. It uses Hugo as Static Site Generator.
I can provide more links for more context and history.

[senft-research]

I feel you have not addressed the question. I was asking are you comfortable with the handbook having a new framework such as MkDocs, and then having a link on the site. Or are you saying the new handbook has to be integrated directly into the site's framework?

[marcuspollio]

Mmh well, I have no particular discomfort with the choices contributors may make 😁
However I am not convinced adding yet another new framework to the four already used currently (i.e. the websites publicly available today) is the most appropriate approach (on-boarding, too complex stack, difficult integration, maintenance, UX/DX). This is one of the points the new unified website project (i.e. freecad/website repo) aims to avoid. It is planned to replace some of the current components by the end of 2026. So in a sense, yes: the Developers Handbook will have a new framework soon (shared by the other reunified web components, that is).

Which specificities of say MkDocs would be most appropriate for the FreeCAD use case? If those are lacking in the new website, they could be eventually added later on.

[senft-research]

What is the framework for the new website project?
I will give a full answer tommorow to your queries as I am currently working.

[marcuspollio]

What is the framework for the new website project?

Please see my first and second answers above and provided links.

[senft-research]

What is the framework for the new website project?

Please see my first and second answers above and provided links.

https://github.com/FreeCAD/Website

I tried to utilize the link to the new website, followed the instructions to build and was left with an empty site. On top of this, it seems that the actual repo itself is actually empty of any content either.

Have I accidentally gotten the wrong repo or my wires crossed?

[marcuspollio]

Hi @senft-research
Yes, what you got is expected for the moment, as the new website is still in a WIP migration phase started only a few weeks ago (from another repository that was used for initial development).
Please wait a few more weeks if you want to try the site locally, after most migration PRs are merged. I can ping you then.

If you want to be involved in the meantime, any particular area of interest to you? See the list on the linked discussion above with general topics, or feel free to ask more details.

[senft-research]

Hi @senft-research
Yes, what you got is expected for the moment, as the new website is still in a WIP migration phase started only a few weeks ago (from another repository that was used for initial development).
Please wait a few more weeks if you want to try the site locally, after most migration PRs are merged. I can ping you then.

If you want to be involved in the meantime, any particular area of interest to you? See the list on the linked discussion above with general topics, or feel free to ask more details.

For the purposes of time, I am going to continue on with my proposal in the initial issue, and go from there.

When the new initiative is active and able to be contributed to, I will look into the matter.

I would humbly propose you put a disclaimer in the readme to make clear the project is not ready for contributions yet.

Thank you.

[marcuspollio]

@senft-research Thanks for the feedback. Should the existing ⓘ Note on the very top of the ReadMe be tweaked as it may not clear enough?
Also, still curious about which specificities of MkDocs could be used for FreeCAD, compared to say other possible solutions?