Move to Zola

[stockholmux]

Several folks in other issues questioned the use of Jekyll, but in the rush to create an initial website it was used out of convenience and at hand expertise to get it out quickly.

Now with a little breathing room, I think it's time to evaluate moving to a new static site generator (SSG). SSGs are very sticky after your site grows and this will only get harder for this site as time goes on. Investing in Jekyll right now seems like an issue on a few fronts:

1) Jekyll is Ruby and requires some tricky setup for those who don't have Ruby already setup on their machine: you have to get the right Ruby version, install the package manager, etc. There is a container but even that is slightly tricky to use and troubleshoot. 2) Even in the incomplete state the rebuild time is pretty annoying. On my machine it takes about 15 seconds to rebuild and that will only get worse in time. 3) Jekyll has some specific requirements for paths to include files. The project inherited a somewhat complicated structure: docs live in one repo (valkey-io/valkey-doc), the command JSON source in another (valkey-io/valkey) and the website in a third, in Jekyll, this lends itself to using git submodules (which are their own problem). 4) The inherited structure and some choices made in valkey-doc requires a decently powerful templating language. Liquid can do this but it's a little messy to achieve what we need to achieve for this site.

I've investigated a few different SSGs recently and tried to see if they can easily handle our site and will be a good choice for years to come.

I built a few proofs of concept and the one that comes out on top based on my evaluation is Zola.

1. It's an easy-to-install single binary, built in Rust.
2. It's much, much, much quicker: the site renders in 100-150ms vs 15 seconds on Jekyll (~150x faster)
3. The directory structure is flexible enough to do away with submodules,
4. Zola uses Tera seems up to the job. Tera is fairly close to Liquid, but a little more strongly typed and has explicitness which will be useful going forward.

Here is the plan, unless someone majorly objects:

1. Create a branch for the zola version.
2. Move content over to Zola.
3. Continue to operate the Jekyll site, adding new content only to Jekyll.
4. The zola version will focus on getting the template and existing content to build locally and match the Jekyll side.
5. Once zola seems feature complete for template, freeze content on the Jekyll side and migrate anything new to Zola
6. Swap around prod and main branch to use Zola.

Move forward with the new world.

[AugustinMauroy]

I love nextjs for static websites (yes, it sounds crazy). But nextjs offers some really cool features. Like OG image generation. Also react is the most used front-end library (not necessarily the best) so as many people as possible can contribute because they are familiar with JSX. Also nextjs is really friendly for SEO.

Also note that the design I did is based on tailwindcss which works very well in the nextjs ecosystem.

PS: I'm open to set up the infrastructure. Make the components ...

[stockholmux]

@AugustinMauroy I'm only vaguely familiar with nextjs. Is the nextjs getting started page a reflection of what's required to start developing with it?

Some feedback that prompted this move is that installing an entire language, package manager, and dependency tree (Ruby/Gem in the case for Jekyll) was too cumbersome for someone who wanted to write a blog post or make some docs updates. Judging by the getting started page, it doesn't look like that nextjs moves us in the direction needed to make the website easy to contribute to. But I'm opening to hearing more if that's a misjudgement.

(FWIW, I'm a Javascript guy from a long way back - since 1998! - but I think that's not typical amongst folks who use or would contribute to Valkey)

[AugustinMauroy]

Is the nextjs getting started page a reflection of what's required to start developing with it?

You only need node. after you can extend with package with npm but npm is install whit node.

it doesn't look like that nextjs moves us in the direction needed to make the website easy to contribute to. But I'm opening to hearing more if that's a misjudgement.

in all cases you need something to process the markdown files. with next you just need to do npm run dev. But we could also provide a devcontainer ???

If you want good example of how nextjs can be used for static website nodejs.org

[kris-ms]

While I'm a fan of Next.js personally, it does not create the simplest contribution roadmap (imo, and specifically for non-infrastructure commits, which should be more common eventually).

I'm also of the opinion that even though React is all the rage in frontend world, it is likely overkill for a website with almost no "interactivity". We'd essentially just be using the JSX component of it as a templating language, which really is a job for a static site generator.

I do think that using TailwindCSS is almost always a good idea though, and I'd love to use it again. Note that this would almost certainly require an additional build step involving some JS bundling business provided that Zola turns out to be the solution.

[madolson]

After spending this afternoon playing with Zola, I am a fan. It seems to work pretty well.

[AugustinMauroy]

perfect !