website core scripts

[luisorbaiceta]

I am opening this pull request to discuss about the core tech of the website. I have preserved the .github/workflow folder added by @lachlancollins and included a .devcontainer folder to unify the development environment and avoid issues such as #240.

I think a correct approach would be to:

• fully decide the tech stack (Docusaurus)
• divide tasks for everyone involved in this first iteration
• migrate release process to automate docs generation (IMO this is a must)

closes #6

[luisorbaiceta]

if docusarus is the go-to solution then we can merge what it has currently been worked on. But for now I think we should set some foundations first

[lachlancollins]

I agree that auto doc generation is necessary - I mentioned some issues that any tech stack would have with the current setup here.

The Docusarus demo is accessible here: https://fastify.github.io/website-next/. I'm very happy with how it's turned out and I'm 100% certain that the custom landing page, etc. can be added easily. However, I have no problems with discussing other options and I'm happy to address any concerns with the Docusaurus demo :)

[luisorbaiceta]

My only concern with docusaurus is only in the long term. I haven't had the time to go through its docs but it seems to me that narrowing down the potential future contributions to only React developers could become a barrier for non framework developers

[luisorbaiceta]

I suggest Eleventy, but maybe add something like Tailwind to avoid all the problems with class-naming and collision and easy things up for future contributors. But I insist, this is only my opinion, and I am really more than fine if for the fastify team is ok to narrow down to React, as the demo page you have shown looks really good..

[luisorbaiceta]

@lachlancollins No matter what tech ends up being used I will start the scripts migration process in this PR

[lachlancollins]

In terms of the use of React, that's a fair enough concern, I've been using React for so long now that it just feels like the default for me. For this particular project however, we would really just be using React as nearly vanilla HTML - at its simplest React can just be used as a templating language where you write discrete parts of your page as isolated components.

For example, this is the "JavaScript" (JSX) generating the header on the demo - aside from the Docusaurus-specific Link tag it is basically plain HTML + CSS and imported metadata.

[luisorbaiceta]

I'm familiar with React. Most of my work is done with Next.js.

Do you think using Tailwind will be a wise solution in the long term for future contributions?

[lachlancollins]

Sorry @luisorbaiceta, I could have checked that by looking at your profile! I think my point about React's JSX being very comfortable for new users is still relevant though :)

I wasn't actually sure where Docusaurus was getting its CSS from until you asked - it bundles Infima with it, which is quite a new framework being developed specifically for Docusaurus. It is possible to add your own custom CSS framework, but I think that would require a lot more work and I personally don't have any issues with the default styling at this point.

[luisorbaiceta]

I wasn't actually sure where Docusaurus was getting its CSS from until you asked - it bundles Infima

In your opinion, will Infima be easy for future contributions to read and understand, or is it better to pick a widely spread system that feels familiar to people that haven't tweaked Infima before?

[lachlancollins]

I don't have any particular worries about using Infima, the class names are very easy to understand (as I would expect from any modern CSS framework) and their site is well documented. Introducing a separate styling framework when it already has everything we need built in might be a bit excessive and more confusing for contributors.

[Xhale1]

I haven't seen Infirma used anywhere else and they state they're not production ready on their site which makes me cautious to use them. I'm up for it, but perhaps using a more industry standard and production-ready tool would be wise?

I personally have a lot of experience and love for MUI (formerly Material UI). It's very widely used, has good docs, and the new styling solution and sx prop should feel familiar to those used to writing native css. Tailwind could be a good solution if we wanted something more lightweight.

I'm super open to any tech stack that makes everyone's lives easier for developing the core site

[lachlancollins]

@Xhale1 yeah I did see that - however from what I can tell, that's trying to say that they wouldn't recommend using it outside of Docusaurus for now with a different library (e.g. Next.js). Infima has been developed specifically for Docusaurus, and the example projects you shared at fastify/website#291 such as socket.io have all chosen to use it.

I use MUI for one of my internal projects, but even as a big fan its components are very "heavy" performance-wise, and there would also be a clashing of styling. I think if we're trying to maximise performance and consistency we should stick with the built-in solution (at least for now).

EDIT: Maybe supabase would be a better example since they have heaps of non-docs pages. While they understandably have added a lot to custom.css, they have not imported any external CSS packages.

[Xhale1]

@lachlancollins that's awesome, I'm down to use it then. If you're working on conversion / versioning stuff then I can work on bringing the landing page and co over?

[lachlancollins]

@Xhale1 sounds great :)

[luisorbaiceta]

@lachlancollins could you please merge what you have worked on? Avoid merging docs folders. Thanks!

[lachlancollins]

@luisorbaiceta hopefully that's everything except the docs!