[WIP] FreeCAD's websites improvements initiative - Step 1 : Homepage and blog migration

[marcuspollio]

Nota bene: this issue is work-in-progress, more content will be added or changed following provided feedback

TL;DR

The gist of this first step of the websites improvements initiative is to prepare the Homepage and the Blog for the coming release of version 1.0 with a new, easier to maintain, documented and more accessible and welcoming website, using the common platform (the static site generator Hugo).

Context

FreeCAD's websites infrastructure has been developed organically over the years. It is made up of various parts which interact differently both for the end-user and the content contributor. Moreover they do not communicate easily with each other, they do have a different logic data-wise and incoherent visual designs. All this contributes to a problematic maintenance and is not advantageous for the project's impact. However, there are a number of positive qualities to be retained from the present state, which can serve as useful references for any improvement.

Early 2024, an initiative was launched by some Design Group contributors to review and improve the situation. This is the first step in a multi-year initiative.

This step has two simultaneous objectives : update the most crucial parts of the infrastructure in preparation for the release of FreeCAD 1.0, and lay the foundations for a set of guidelines and documentation for the websites infrastructure and maintenance.

Problems

Linked issues

Requirements

Note that this is a subjective appreciation, no strict criteria have been used.

+++ indicates a high importance or a high fulfillment (works great)

++ indicates a medium importance or a medium fulfillment (works ok)

+ indicates a low importance or a low fulfillment (works poorly)

General

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Type	does not apply	custom dynamic website without database	dynamic CMS with database	static site generator
Softwares and frameworks	does not apply	Bootstrap, jQuery, PHP, Crowdin	PHP, MySQL/MariaDB	Go, JAMStack
License	+++ most free and open possible	++ MIT and proprietary (Crowdin)	+++ GPLv2	+++ Apache 2.0
Development model	+++ open or community-based	++ Community and private company (Crowdin)	+++ WordPress Foundation and community	+++ Community
Timeline	+++ long established and long-term support	++ 19-77% all web, >12 years, unknown (Crowdin)	+++ 43% all web, >20 years	+++ <1% all web, >11 years
Software cost	+++ free of charge or moderate price	+++ free, free for non-commercial Foss (Crowdin)	+++ free, most plugins are free	+++ free, most themes are free
Accessibility	+++ most devices and languages	++ possible but implementation lacking	+++ extensive guidelines and tools	+++ extensive guidelines and tools
Performance	++ efficient and low bandwidth	++ simplicity helps with speed, images make it slow	++ needs database queries, but caching can help	+++ very fast, simplicity helps, images preprocessed
Security	+++ most secure and reliability	++ needs lib updates and some knowledge	++ core secure if updated, attention to plugins !	+++ quite secure, specially with no JS

Workflow

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Content management	+++ most WYSIWYG for low barrier of entry	++ needs a bit of HTML/CSS know-how	+++ integrated Gutenberg block editor	++ needs a bit of Markdown know-how
Medias management	+++ most WYSIWYG for low barrier of entry	++ needs a bit of HTML/CSS know-how	+++ integrated Gutenberg block editor	++ needs a bit of Markdown know-how
Blog posts support	+++ integrated with filters	+ possible but not in current form	+++ main "raison-d'être"	+++ main "raison-d'être"
Translations management	++ translation in context	++ not in full context, requires Crowdin and scripts	++ needs a dedicated plugin, see below	++ needs some setup, but then easy
Style management	++ easy adjustments while customisable	++ needs a bit of HTML/CSS know-how	+++ themes and templates	+++ themes and templates
Revision control	++ git integration for changes follow-up	+++ git for all files, continuous deployment	++ git for wp-content, continuous deployment	+++ git for all files, continuous deployment
Deployment	++ easy dev > staging/testing > prod setups	++ needs a bit of git know-how	++ needs a bit of git know-how	++ needs a bit of git know-how
User accounts management	++ single easy and secure system	does not apply	++ user management with roles in wp-admin	does not apply, can have authors data files
Maintenance and debugging	++ status, admin functions, setup, backups	++ no easy maintenance access, backups via git	++ many status, admin, backup tools	++ setup needed, backups via git

Scalability

Requirement	Importance for FreeCAD websites	Current Homepage implementation	Current Blog with WordPress	Unification with Hugo SSG
Extensibility and integration	++ large existing possibilities and reusability	++ needs development, but no real limits	++ large ecosystem and examples	++ needs development, large ecosystem, but no real limits
Plugins	++ extensive choice, easy setup, support	does not apply	++ large choice, setup and support variable	++ front-end framework or headless CMS possible
Custom	++ ability to accommodate custom solutions	++ needs development, but no real limits	++ using WordPress hooks	++ using Go modules

Proposal

• Make the Homepage and the Blog work together, on the same platform (Hugo) with a similar workflow used FreeCAD-wide (Pull Requests to the Git repositories, here with Markdown files) . This way, the Blog becomes really part of the main website, and not a additional different body (is this ringing any bell ?) This allow to reuse some of the already existing content (converted to Markdown files) while deprecating separated and cumbersome maintenance parts (the present Homepage and the Blog) .
• Develop a simple to use design that promotes the FreeCAD project efficiently, for the version 1.0 release and the future. Every page or external link should be accessible in 3 clicks at most (ideally 2 for the most used ones). The experience should be on-par for every language and device (desktop, mobile, etc.). Also take the opportunity to improve the donation pages and provide a pleasant space for release notes.
• Set some simple documentation for content contributors to the new unified website (blog posts, translations, medias, texts), while providing a deeper access to experienced contributors (web developers and admins) to tweak advanced features (theme, templates, config, etc.). Instructions for managing the different environments (development, testing, production) and version-control are included. Guidelines to ease maintenance, workload and prevent security issues are included. A references section and a list of contacts within the FreeCAD project (admins, editors, translators, etc.) to welcome new contributors are also included.
• Setup simple and efficient Testing and Production environments with Continuous Integration and Continuous Deployment. For Testing directly on the repository with GitHub Pages and for Production on the dedicated web server.

Design

Structure

_TODO: update with latest revisions_

WIP mockups

**Homepage**  **Features Page**  **Download Page**  **Release Notes Page**  **Previous Releases Page**  Blog, support, community, contribute and donate Pages to be added soon

Deliverables

• The completed and validated design, before the implementation begins.
• The base of documentation and guidelines, to be improved while the site is implemented.
• The website migration bringing together the Homepage and the Blog, with previous content or placeholders for future content additions.
• A new repository for follow-up tasks, issue reports and improvements.

Resources

The design and development work is mainly carried out by JigglyBuff (zortane) and marcuspollio, with inputs and feedback from the Design Group (mainly Max, Obelisk, Mistermaker, Kadet, Alex) and some maintainers (Chris and Kurt). Some of them have offered to do code review, testing or content contributions. Translators have not been formally contacted at this time. A larger request for content (texts, illustrations, video, example files, etc.) will be made after the first deliverable is completed.

Indicative timeline

• Complete this design task and incorporate feedback : from now to mid-June
• Setup of a development environment : from now to mid-June
• Feature Freeze of FreeCAD : 3 June
• Content contributions request (texts, illustrations, video, files, etc.) : from early June to end of August
• Documentation and guidelines draft : from early June to end of July
• Migration of the new unified website in a testing environment with GitHub Pages : from mid-June to end of June
• UI Freeze of FreeCAD : 24 June
• Selection of contributed content and its addition to the website : from mid-July to end of August
• Testing and improvements of the new unified website : from early July to end of August
• Cleanup of the present Blog database (posts, tags, user accounts, etc.) : from mid-July to end of July
• Backup of the present Blog database, conversion to Markdown files and addition to the new unified website : early August
• Request for translations and their addition to the website : from early August
• Finalization of the documentation and guidelines : end of August
• Setup of the final production environment of the website : early September
• Buffer time for last-minute finishing touches : from early September
• Release of the new unified website : with the release of version 1.0 of FreeCAD (between mid-September and end of 2024)

Questions

• more to be added soon

[yorikvanhavre]

My 2 cents here, I'd say why not, indeed having both the blog and the website as one single structure seems a good thing, and wordpress is certainly a capable platform to do this. However, I also see problematic points to be studied:

1. "one of the most troublesome parts of the FreeCAD websites ecosystem (the present Homepage)" seems an arbitrary assessment to me. The bog, for ex, is currently far more "problematic" than the homepage. As I agree having both into one would be good, problems should be identified a bit clearer.
2. The simplicity of the current homepage is what allows it to be open-sourced and guarantees it to be easily tweaked and fixed by contributors. Being done on wordpress, it basically ceases to be open-source. That's a problem for an open-source project :)
3. We chose wordpress for the blog because we needed a blog and it was easy & quick, but being tied to a platform quickly becomes a problem. See our mediawiki problem. Now we're wanting to go back to a simpler, markdown structure. How do we guarantee the same will not happen with wordpress.
4. If it's not open-source anymore, that means it relies on designated people, as the community is not able to PR anymore. How do we guarantee maintainability in that case.
5. Translations is something very important to the community, and needs to be very carefully designed. Relying on plugins can easily become a problem (see the wiki experience).
6. How would the after-download donation/thankyou system work?

[marcuspollio]

Hi @yorikvanhavre Thanks for your feedback and sharing your concerns !

You're not wrong in saying that using a fully-fledged solution like a dynamic CMS using a database (WordPress), it's posing a number of obstacles to the open nature and accessibility for contributors of this part of the FreeCAD project, as accounts need to be set up, not everything is as transparent as on a git repository, there's the question of assigning specific roles, maintenance and the big point of translations too.

So the plan has a bit changed in between. The idea is to continue this effort to reunite the main website and the blog, and to go instead with a static site generator. In this case Hugo. From our investigations, this solution seams more appropriate than Jekyll (used for the FPA and the Developers Handbook) for this step 1. Its simplicity, flexibility, extensive community, fast !, very few plugins needed (most functionality out-of-the-box like minification), native multilingual support make it a sensible choice, in spite of the initial learning curve (mostly due to Go templating).

We are currently setting up a development environment and doing some tests, while advancing the design. Mockups will be posted here soon.

The initial post has also been updated to reflect this change. Open to feedback as always =D

[yorikvanhavre]

So the plan has a bit changed in between. The idea is to continue this effort to reunite the main website and the blog, and to go instead with a static site generator.

YES! I like that solution much. My own blog is entirely composed of markdown files and uses a static generator (pico). Once it's set up, it's pretty straightforward, and it's all a question of creating templates, pretty much like wordpress. And you can keep the contents in a clean folders structure that is gitable, browsable and everything good.

Hugo seems appropriate, I looked at it at the time I set mine up and seemed too hard to install (laziness always :sweat_smile: ) so I went for pico, but pico is less actively maintained, which is something I'd prioritize for FreeCAD

[yorikvanhavre]

@prokoudine any insight here?

[concretedog]

Hi all, I'm a regular contributor writing posts on the FC Blog. I'm not as technically versed in the web stuff but I am very much available if you want any insights as to what I/we would like in terms of functionality on the blog. Until earlier this week there were some really big functional issues with the blog, like no page break/truncation of posts, titles of posts not being links, no author names etc. After some research I suggested a wordpress template that Alex implemented and mitigated some of this. FWIW re the blog it's worth noting that it has a variety of content from tutorials to WIP updates etc so it needs a variety of stuff to work for all types of content well. One thing currently missing for example is image expansion on click or rollover which makes detailed tutorial content a pretty poor experience for the reader. Anyway.. happy to trial stuff/feedback or help in any way I can. Jo

[prokoudine]

FYI, I've just installed this lightbox plugin: https://archetyped.com/tools/simple-lightbox/

[marcuspollio]

[...] want any insights [...] happy to trial stuff/feedback or help [...]

Hi Jo, Yorik and Alex, thank you for your input !

Indeed, the general idea is to integrate the Blog (called "News" in the Structure mockup above, the name is open to change of course) a lot more into the general website. I'll try to post mockups of the preliminary design next week =D

It's planned to have the most recent post (title, featured image and summary if space allows) of every blog/news category displayed on the Homepage. Nothing is settled yet, but the gist is to have a base taxonomy with six different categories (announcements, events, developments, tutorials, showcases and highlights) that more-or-less match the current ones in WordPress. The first three are more "official" posts while the three latter are more "community" posts, although the difference is somewhat fuzzy and arguable ;D The new "highlights" one is still a bit vague and very open, but could be a way for community vote/award to highlight the work/involvement of some individuals or groups on projects related to FreeCAD, e.g. educational, external workbench/addon development, particular regional/language group or even slightly different topics about design, CAD, documentation, community/participatory projects, every month or season. So every category will have a dedicate template and prefilled archetype (a way to add new per-formatted content easily in Hugo). When we reach this point (tailor the template and archetype) we will certain need your help (and Alex's and others).

The same goes for translations : ease as much as possible the work to add and manage content, despite the lack for the moment of WYSIWYG like WordPress (a headless CMS would be needed, maybe for later). Also, the way Hugo works, most non-list pages act a bit like a blog post, e.g. release notes, downloads pages, dedicated events pages, learning pages, donations pages, translations, etc. It's just the way the templates reuse the content and front matter data that changes. So anyone familiar with Markdown and after adding a few posts in the blog/news will be able to tweak/add content to the whole site. At first, on-boarding should be easy, then with time digging more into the powerful features like templates will make more sense.

We'll setup a testing environment in a repository soon, still very much work-in-progress, but it will provide a test bed for improvements to the general design, interaction and content management.

• Also, contrary to WordPress that is using a database, a static-site generator uses a hierarchical folder structure (like on one's device). With time, the blog/news will accumulate quite a lot of posts making a very long blog/news section folder. Which organization structure is preferred ? By date (e.g. 2022, 2023, 2024, 2025 folders) or by category (e.g. announcements, events, developments, tutorial, showcases, highlights folders), or something else ? Note that all these informations (date, author, language, tags, categories, etc.) will be in the front matter of every file too, so it's more to help organize the website structure.

• Concerning the blog/news posts, the design we're heading to for the moment is a bit "old-school" without any comments possibility. Is this feature needed ? Do we have the resources to moderate them ? Are comments on the main website a good place to engage with the community or do we already have sufficient places for that ? It's open.

• We will also quickly need help to improve the website documentation so content can be quickly added as soon as the new unified website enters a close-to-production state. The current one is very lacking. I tried to add some more on the Developers Handbook but did not progress much since.

• The current WordPress blog content will also need to be ported to the new website. Do any of you know a good WP to Markdown converter (ideally tailored for Hugo) ? There are some here, and there and probably more, but haven't tested any yet. On the indicated timeline above, this will need to be done around end-July early-August.

Finally, we will keep you all informed as this progresses, hopefully fast enough... 1.0 is around the corner XD So any help is most welcome. Thank you again !

[yorikvanhavre]

Commenting on posts could be done in many ways that do not require additional moderating. Specially with social media that becomes easy, one could imagine posting new articles automatically to twitter/mastodon/facebook/forum/etc, and let people comment there.

[yorikvanhavre]

@luzpaz this might interest you too

[marcuspollio]

Some draft mockups have been added in the first post above. The News, Support, Community, Contribute and Donate Pages will be posted soon.

[yorikvanhavre]

I liked that! Some remarks:

1) It needs to be responsive: How will it look on mobile screens? 2) The release notes are usually built on the wiki. Will there need to be work each time to "port" them to the website? Of course we would like for the wiki to become markdown some day. There might be something to be done there... 3) I don't think we should put the sponsors on the main web page. The main web page is for users, not for sponsors. If you want to sponsor FreeCAD, it's because you trust the project and want to help it, not because you want to promote yourself. Look at https://blender.org for example, although they have huge sponsors, they don't appear on the main page. IMHO it is very important to make that clear 4) One aspect I like in the current website, is also that it "feels like yours". (Same for blender.org). So I'd put some effort in making it easy to browse, use bigger text, few and easy to find buttons, etc. We want kids to use FreeCAD too. That's the difficulty we need to master here, have something cool for both kids and for CEOs ;)

[marcuspollio]

Hi @yorikvanhavre ! Thank you for the feedback.

1. responsive [...]

I haven't done a mockup for the mobile version. If you look at the general layout, it's a grid (rows with 2 or 3 columns). In the mobile format, each "cell" will follow one after another. You can have a look at the base theme I'm developing our custom forked theme on here. Is it good enough ?

2. release notes [...]

It's indeed unfortunate to duplicate some effort on two places. However, pending further progress on the wiki/documentation, we felt it was important to promote the release of version 1.0 in an attractive way on the new unified website. For now, what is proposed here on the mockup (and is of course subject to change) is to highlight in a simple manner the 5 to 7 main great features of the new release (TNP mitigation, Assembly, Material, Sketcher, CAM and BIM rename, UI/UX and Measure), while having links to the full notes on the wiki. We don't have the resources yet to promote it fully à la Blender way, later maybe =D So yes, this question is an aspect to consider as both the new unified website and wiki/documentation projects progress. The time available before release is too tight for properly engineering it, so let's keep this aspect on the TODO list when 1.0 is out. I guess the main question is: where is the best place to highlight new releases ? How do you feel about it ?

3. sponsors on the main web page [...]

I completely agree, it's not required and could convey a false signal. This aspect was suggested by looking at the Godot, QGIS and other FOSS websites. With a dedicated donations page like currently, having the same information on the HomePage is redundant. Let's make a neat donations page and leave only the mention of the FPA association on the HomePage. Is it OK for you ?

4. feels like yours [...]

Absolutely, and you can tell it's still very much Work-In-Progress. The general idea is to have a website that's easy to use, to the point, with a limited number of pages (which also helps with maintenance) and where the information is clear and accessible. As we'd like to have as little JavaScipt as possible, we still haven't decided whether to include a search function or not. Any opinion on it ? So, for the time being, the chosen approach is that of an “old-school” site, i.e. not a product where the web experience is the key focus to generate more traffic or revenue (e.g a social networking platform, an online store or a search engine), but rather a simple page-structured website with simple navigation and little interactive content (like the current website). The intention is for users to use the FreeCAD software and engage with its community instead of spending time on its website (be in the room with others rather than on the doorstep reading the menu card). However, in developing the theme, we thought we'd have a few aspects that evoke the CAD domain, design, etc. with subtle colors and patterns, rather than a more generic site appearance (but it won't be a machine gallery or Sketchfab-like). Do you have particular suggestions (composition, text size, buttons, colors, etc.) ?

---

Here are a few other questions to help move the design validation forward :

5. News/blog categories and management. Are the six categories proposed above (announcements, events, developments, tutorial, showcases, highlights) validated ? Any preference for news/blog folders managements (category or year) ?

6. Content production. The idea, when the design is more-or-less endorsed, is to ask the wider community to contribute content for the website : texts (and translations later), illustrations (screenshots, pictures of IRL projects, events, renders, etc.) and examples models (the repo hasn't been updated in 4 years... updates ones, new version 1.0 ones, all ideally with a small description text). This needs a little organization to decide what, how many, how and which ones. I'll ask among the Design Group if there's people wanting to help organize it. Any recommendation ?

7. Promotion videos. In the mockups above, I left 2 places where videos could fit (on the HomePage just below the news and on the 1.0 Release Notes). But the big question is : do we want videos ? Is the general "Discover FreeCAD" or the temporary "Version 1.0" more useful ? Does the FPA want to contract a talented member of the community for it ? I personally cannot commit to producing such content but can help define general guidelines if needed.

I'll try to update and post new mockups here very soon. Thank you =D

[yorikvanhavre]

Cool! I think this is going well. Agree with everything above.

5. categories [...]

I would think this needs to stay flexible, and things might change in the future... I would try to propose a sensible choice now, and define a smart system so it's easy to manage

6. content [...]

Definitely! Involving the community is the best way to go

7. videos [...]

Yes, the problem is always "who is going to do them" :) We are never sure if we'll have videos and when. Here too I would try to stay flexible