feat: rewrite to Astro

[DLakomy]

Fixes #117

Hello.

I've learned Astro yesterday and thought I might try rewriting your webpage to a static one. I've got nothing against JavaScript on your page, but saw an issue on GitHub.

What I optimized for:

1. Similarity to React, so the current maintainers have no trouble switching. This is why I chose Astro.
2. Limited refactors, so it doesn't take long to implement (it's difficult to merge updates from master during a full rewrite).
3. 100% similarity, pixel for pixel, to make it easier to review. I've spent hours tweaking it and trying not to leave accidental changes (especially in the content, it's surprisingly easy to loose a paragraph...), but to be honest I'm not 100% sure I've got everything. The icons are slightly different on the documentation subpage. I guess it's a matter of fontawesome's version.
4. Zero JavaScript at runtime (after running npm run build you can run find ./dist -name '*.js' and see no results).

Some notes:

1. There is a TODO comment in src/components/InlineEditor.astro. It's not blocking this merge, just a suggestion for the future. I guess this would help make Flix more popular (which I hope will happen!).
2. I've replaced the carousel (Visual Studio Code Support section on the home subpage) with a simple grid. I can try to make a pure CSS carousel, but maybe it should be removed and just point to the VSCode webpage. What do you think?

How to test:

1. npm run build.
2. Serve dist subdir. For example cd dist && python -m http.server 8000 and open http://localhost:8000/ in your browser. Actually, now you can even read that with curl :D
3. There is a question in FAQ: "This site requires JavaScript" and similar. Shall I redact them, as no longer standing?

If you're interested in merging, I'm waiting for your feedback and can check again before merging, to make sure no text is lost.

[magnus-madsen]

Thanks @DLakomy. This is an interesting experiment. I will have a look.

Can you sell me on Astro? I assume its a static site generator. But why this one specifically?

I will try it out locally... and report back.

[magnus-madsen]

A few more questions and comments:

• How did you go about the refactor?
• Are URLs preserved? We don't want to break links.
• The code font is not the same or the same size?
• Instead of bundling our own textmate grammar, perhaps we could use highlight.js?
• Does the use of Astro mean that the website will work (mostly) without JavaScript?

[DLakomy]

Can you sell me on Astro? I assume its a static site generator. But why this one specifically?

Sure. Some background: I'm not a frontend dev, so take what I say with a grain of salt (or a bucket of salt). I sometimes have to write a frontend, though, and in these cases I like solutions that are easy to learn and have a simple tooling. Since I know I won't be able to maintain this site long-term after this experiment, I wanted to make the codebase as approachable as possible for the existing team.

I chose Astro because:

1. It's a bit similar to React (uses JSX), but optimized towards mainly static apps with islands (see https://docs.astro.build/en/concepts/islands/). I assumed it will make it easier for the current maintainers to switch to. It's also possible to rewrite from React to Astro gradually, but given the small size of the website I thought it's easier to just do it all at once and reduce dependencies. See: https://docs.astro.build/pl/guides/integrations-guide/react/. I think it would be theoretically possible to keep the page as is and it would render React on the server (so the client doesn't have to), but it would make the webpage dependent on two big dependencies with very little value.
2. It allowed me to rewrite the page as is for now (unlike e.g. Hugo, which would involve significant changes).
3. It leaves multiple good paths open for the future: adding or building a component library, switching to MDX, etc. These can all be adopted gradually. I think Rock the JVM uses this approach (MDX). It's good that all of these can be done gradually, not necessarily all at once.

What alternatives I've rejected:

1. Hugo. I never used it, but I think it might be good for a static site; however, it would involve significant rewrite.
2. htmx - Would enable partial updates without full page reloads, while keeping the page working without JS. But the site is already small and fast. It would also require a backend, which felt unnecessary here.
3. Plain static HTML + CSS. And then I thought: „how do I synchronise the menu-bar thing between subpages”? Astro addresses exactly this problem in a very easy way (Layout.astro describes the common structure).

How did you go about the refactor?

I've been rewriting page by page. The first one, Home, I initially tried to use LLM, a free one. Never more... It correctly rewrote like 50%, created a nice scaffolding, but the rest one I've been fixing manually. It also didn't handle this trap in JSX (Astro 7 handles whitespaces like JSX now by default), I mean:

some text
<a href...>in a new line>

Renders as some textin a new line. I fixed by adjusting linebreaks manually, but now I know it's not the best solution (I think {' '} is).

In terms of verification, I've been carefully scrolling flix.dev and localhost next to each other (visually and the effective html) and checking if it's now identical.

The rest (the pages after Home) I've rewritten manually. I think it was a better approach. The verification was easier, because I essentially took the original React and wrote Astro components that would make it render the same.

Are URLs preserved? We don't want to break links.

I think so (I've checked for instance https://flix.dev/principles/ vs localhost:8000/principles/ and it works. The URLs are defined in Layout.astro, see const navLinks = ....

The code font is not the same or the same size?
Instead of bundling our own textmate grammar, perhaps we could use highlight.js?

The renderer is Shiki and Prism is an option. I have no idea what is Prism, but Shiki, if I understand correctly, renders on the server and is kind of built-in. So we could use highlight.js (not sure how, but I'm pretty sure it's possible), but then we don't take advantage of the built-in solution (and I guess it would involve using JS on the client side). Some details here: https://docs.astro.build/pl/guides/syntax-highlighting/. This also explains why the font is not the same. It's a different renderer and I couldn't find an identical theme among the bundled ones. I would have to write a new one, I guess.

Does the use of Astro mean that the website will work (mostly) without JavaScript?

It depends. The code I've submitted uses exactly zero JavaScript, because everything is rendered during npm run build, even syntax highlighting. So there is no JavaScript needed, unless you opt-in. I'm not sure if highlight.js would involve JS on the client.

[magnus-madsen]

Thanks-- I am on vacation but I will revisit this when i am back (August)

[magnus-madsen]

Thanks @DLakomy for your write up and hard work. I've looked into Astro and it seems like a good choice, so I would like to proceed towards merging this PR! :-)

What I will do is to review it and give some feedback. I then suggest that some feedback is fixed now and some feedback can be resolved in follow-up PRs.

Are you up for that?

[magnus-madsen]

First things first: I need you to add your name to AUTHORS.md to affirm that you contributions become open source.

[magnus-madsen]

Overall just a few minor comments and questions.

I will now take a look at the content page-by-page.

[magnus-madsen]

We can update this QA after the merge 😆

[magnus-madsen]

A few more comments:

• The favicons shifted/slightly changed. Is there a reason for that? And should we perhaps use a npm package instead of CDN?
• The carousel of VSCode images on the home page is now just a 4x grid. Perhaps that is OK. Otherwise we need JavaScript right? Hmm. Perhaps this: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Overflow/Carousels or some other Astro component can help us?
• The code font is slightly off. That would be nice to have fixed (not sure what the issue is).
• In later PR, we should probably use a dynamic grid/flexbox for the VSCode page.

[magnus-madsen]

Overall this looks great! I don't think much remains to be done before it can be merged. Just chasing a few loose ends.

[DLakomy]

Thank you for the review. I plan to to work on it this weekend.

For now, some quick answers (apart from the ones I've answered in the relevant threads; hopefully I've answered all of them, except for inline/not inline cosmetics, I address them here):

1. About inline vs not inline: I'll do according to your suggestions. I've got no strong opinion and it's purely cosmetic at the moment.
2. The carousel of VSCode - there is something like that: https://github.com/claudiabdm/astro-carousel. I didn't use that, because I don't know your stance about dependencies likes this. Personally I'd prefer to avoid a carousel on a mostly static page, to avoid fighting with browser compatibility (especially Safari...). Note that the current one seems to be broken 😬 Clinking on the arrows crash the browser (Safari/Chrome). However, it's your webpage, so I can see what I can do. Just let me know if I should avoid js/dependencies.
3. The favicons shifted/slightly changed - it was very difficult to find some of the brand icons. Maybe a proper frontend-dev would do it effortlessly, but I just took the newest fontawesome, to be able to raise this PR faster. Should I try to match the previous ones? About CDN vs NPM: I chose CDN (and added integrity), because a CDN has been used already. AFAIK there is no consensus among frontend devs, whether NPM or CDN is a better solution.
4. The code font is slightly off - do you mean color / spaces between the lines / font size? It might be difficult to make it 100% as is on flix.dev now, but will try. I'll get back to this after investigating other code renderers, as it might result in different circumstances.
5. In later PR, we should probably use a dynamic grid/flexbox for the VSCode page. - when an issue on GitHub is raised, please let me know. Maybe I'll give it a try.

BTW I'm not marking the comments where I've answered as Resolved, in case there are follow ups.

[magnus-madsen]

Thank you for the review. I plan to to work on it this weekend.

And thank you for your efforts.

1. About inline vs not inline: I'll do according to your suggestions. I've got no strong opinion and it's purely cosmetic at the moment.

Great!

2. `The carousel of VSCode` - there is something like that: https://github.com/claudiabdm/astro-carousel. I didn't use that, because I don't know your stance about dependencies likes this. Personally I'd prefer to avoid a carousel on a mostly static page, to avoid fighting with browser compatibility (especially Safari...). 

How about we leave this for later, and just show a single screenshot?

3. `The favicons shifted/slightly changed` - it was very difficult to find some of the brand icons. Maybe a proper frontend-dev would do it effortlessly, but I just took the newest fontawesome, to be able to raise this PR faster. Should I try to match the previous ones? About CDN vs NPM: I chose CDN (and added `integrity`), because a CDN has been used already. AFAIK there is no consensus among frontend devs, whether NPM or CDN is a better solution.

I don't really care so much about the specific icons; I care more about reducing the usage of code we don't control. I am not a webdev, so I am not entirely sure what is best practice here.

4. `The code font is slightly off` - do you mean color / spaces between the lines / font size? It might be difficult to make it 100% as is on flix.dev now, but will try. I'll get back to this after investigating other code renderers, as it might result in different circumstances.

Its not the same font on my machine, but a good question is what font it should actually be. The CSS inspector in firefox shows: font-family: "Monaco", "Menlo", "Ubuntu Mono", "Consolas", "Source Code Pro", "source-code-pro", monospace. Perhaps we could simply try that to start with.

5. `In later PR, we should probably use a dynamic grid/flexbox for the VSCode page.` - when an issue on GitHub is raised, please let me know. Maybe I'll give it a try.

Sounds good. We can create some follow-up issues once this PR is merged.

BTW I'm not marking the comments where I've answered as Resolved, in case there are follow ups.

Thanks and good plan.

[DLakomy]

Today I've managed to fix the most tricky parts (at least from my point of view).

1. The code examples should look the same. font-family and some layout css was slightly different, hence something felt off. I've tested on macOS, Safari and Chrome. It looks almost the same as it used to. Except for the colours and some more code is visible on the right.
2. I removed the CDN and managed to find better icons, and fixed the layout. It took some time, but the Documentation page is identical to the previous one.

BTW I've updated my knowledge on CDNs vs npm packages. For now, CDNs are good for prototyping (it's worth adding integrity, though), but they don't have the advantages they used to. Browsers no longer cache assets across domains (due to user tracking concerns). Additionally, the npm package approach allows for better tree-shaking - only the icons actually used are shipped.

I plan to address the rest of tomorrow.

[DLakomy]

Hopefully I've covered everything. Please let me know if I missed something, or something more needs to be done.