Rewrite to Astro, to make the website static

[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?

[magnus-madsen]

What does a file like this do?

[DLakomy]

It's a direct equivalent of the original:

function Answer({ children }) {
    return <div>{children}</div>;
}

In Astro it's not possible to write JSX in the frontmatter (the lines between ---), so AFAIK this is the only way to create a component. Source: withastro/roadmap#164

I wasn't sure whether to rewrite this (which I did) or to inline this div. I made a component to keep faq.astro similar to Faq.jsx, easier to review. We can keep it (it would make it easier to change how an Answer looks like in the future) or inline it, so nobody is wondering why it's here. I have got no strong opinion.

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