[Proposal] Modernize Valkey Website and Allow Serving GLIDE and Valkey-Admin Documentation

[alexey-temnikov]

Proposal: Migrate Valkey Documentation to Astro

Currently, Valkey documentation is spread across multiple websites: valkey.io, glide.valkey.io, and valkey-admin.valkey.io.

This issue proposes updating the current engine from Zola to Astro, and Starlight. The goal is to make it easier to integrate more complex dynamic content and richer technical documentation, while also improving consistency across the Valkey documentation ecosystem.

Prototype

A prototype of the current website migrated to Astro is available at valkey.alexey-temnikov.com.

The source code is available in the valkey-site-astro repository.

This is a complete prototype. It still requires some tuning and a few fixes, but it is already fully functional. The current version supports documentation search, includes a slightly updated UI/UX, provides navigation that is consistent with the Valkey GLIDE documentation, and maintains compatibility with the existing valkey-docs content.

Screenshots

---

Ideas, suggestions, and concerns are welcome.
If this approach looks good, I would like to continue improving the prototype and bring it to a polished, production-ready state that can be used in valkey.io.

[stockholmux]

Hey @alexey-temnikov - could you explain how Astro itself adds value?

Part of the feedback we had that lead to choosing Zola was that we needed a very low friction contribution process. Zola is a single binary to install with no package managers nor dependencies, no containers, etc. Astro looks like it requires quite a bit (node, ppm, all the dependencies that brings in). Our contributor target would be unlikely to have these things, so this change would create more friction for contributors, not less. Can you prove that this move lowers friction?

As far as the rest, I don't mind the style and universal search with pagefind is super cool. But that doesn't seem linked to the rebuild.

My initial peek at the your version seems like a good direction from a UX/Visual approach that can probably be accomplished with incremental changes using existing tools, not a complete re-write and requiring everyone to change platforms yet again.

[alexey-temnikov]

Hi @stockholmux,

Fully understand the ease-of-use concern. While a Node-based build system may seem slightly more complex due to the dependencies, contributions remain very similar, as new content is driven by Markdown files and the site remains fully static. In a sense, it makes it easier to update and maintain documentation thanks to the new capabilities.

The biggest value is the ability to easily unify documentation with more modern capabilities and make it consistent with glide.valkey.io and valkey-admin.valkey.io, along with providing easier-to-use docs for Valkey and reducing the effort required for documentation maintenance.

If this approach doesn't work, would be happy to hear what might be the possibilities on bringing all 3 websites under the same unified website and look and feel.

[stockholmux]

@alexey-temnikov FWIW, on an earlier iteration of this site I tried to personally guide multiple Valkey engineers on how to install Jekyll (Ruby based, but a similar number of moving pieces: runtime, package manager, dependencies) and it was harder than you might imagine for those not familiar with those ecosystems. It was too much to ask for many and they just gave up.

On the other end, we have marketing-type folks that interact with this repo and they know very specific pathways and they have just gotten competent with Zola. So a revamp would be hard for them as well.

I want to dig into what you mean by 'modern' - can you define that?

I'm not opposed at all to unifying the content in some representational way. It makes sense that someone would come to Valkey.io to know about the other related projects and that you could search one place, etc.

In my mind, there needs to be an abstraction between content and representation (templates, styles, etc.) and it should be extensible, so later we could add documentation for valkey-foo, valkey-bar, etc. along side the docs for GLIDE, Admin, etc. Each of those would be content only. The only content in this repo would be blog posts, non-technical marketing materials, and about us type documents.

[madolson]

@stockholmux One thing we talked about in the past is building some automation around rendering pages so that most people don't need to install the SSG, you can just do the markdown and send the PR and verify it on github. I came up with a pretty simple lightweight way that generates on another github page site. We can only keep ~25 pending views, but that should be enough for us for the time being.

We should do that regardless, but might help alleviate some of the concerns with not having people install something new.

[madolson]

Semi related, Google also recently published some guidance on how to optimize for AI: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide. I guess let's make sure we're following all of those best practices in addition to ones for humans if we can.