Proposal: Migrate from Jekyll to VitePress

[maxrjones]

Summary

I'm opening this issue to propose migrating zarr.dev from Jekyll + Minimal Mistakes to VitePress, following the approach successfully used by zarrs.github.io (live at zarrs.dev).

Motivation

The current Jekyll setup has several pain points:

• Complex build toolchain — Ruby + Bundler + Pixi/RVM, with a Dockerfile needed as a fallback. Contributors have reported environment issues (Conda environment error trying to build website locally #130).
• Dated theme — Minimal Mistakes v4.26.2 ("dirt" skin) is functional but visually dated and limits design flexibility. The lack of progress on open issues (Add row of primary features #38, Remove "recent posts" from main page #39, Add multiple header images #40, Bug: Outdated Twitter Logo in Zarr homepage #104, make adopters page more compact #155) may be influenced by the themes constraints.
• Limited interactivity — No straightforward path to add interactive components (e.g., tabbed code examples, dynamic content).
• Ruby dependency — The broader Zarr ecosystem is Python/JS/Rust. Ruby is only used for this one site, adding cognitive overhead for contributors.

Why VitePress

• Node.js-only — aligns with the JS tooling already used across Zarr repos like conventions and the zarrs website.
• Fast — near-instant hot module replacement in dev, optimized static output in production.
• Vue components — easy to add interactive elements (tabbed examples, live demos) when needed.
• Proven in the ecosystem — zarrs.dev and geozarr-site already use VitePress successfully.
• Minimal dependencies — zarrs.github.io runs on just vitepress + one syntax highlighting package.
• Built-in features — search, dark mode, sidebar navigation, and responsive design come out of the box with the default theme.

Scope

Content pages to migrate:

Page	Source
Home (/)	index.md
Adopters (/adopters)	adopters/index.md + adopters/logos/
Community (/community)	community/index.md
Conventions (/conventions)	conventions/index.md
Datasets (/datasets)	datasets/index.md
Implementations (/implementations)	implementations/index.md
Office Hours (/office-hours)	office_hours/index.md
Slides (/slides)	slides.md + slides/ directory (Reveal.js assets)
Blog posts	_posts/ (2 posts)

Additional migration tasks:

• Navigation — Convert _data/navigation.yml to VitePress config.mts (nav + sidebar)
• Redirects — Preserve numcodecs_redirects/ (23 redirect pages) using static meta redirects
• Static assets — Move images/, favicons, and CNAME to public/
• GitHub Pages deployment — Replace Jekyll build with VitePress build in GitHub Actions (reference: zarrs deploy workflow)
• Social links — Map footer links (Bluesky, Mastodon, GitHub, Zulip) to VitePress social links config

Reference implementation

zarrs.github.io (source, live) demonstrates the target setup:

.vitepress/
├── config.mts          # Site config, nav, sidebar, analytics
└── theme/
    ├── index.js        # Theme entry
    ├── Layout.vue      # Custom layout (optional)
    ├── custom.css      # Brand colors and overrides
    └── components/     # Custom Vue components (optional)
public/                 # Static assets (logos, CNAME, etc.)
index.md                # Home page (VitePress hero layout)
package.json            # Just vitepress as devDependency
.github/workflows/deploy.yml  # Node 20 + npm ci + vitepress build

Files to remove after migration

• _config.yml, Gemfile, Gemfile.lock
• Dockerfile, pixi.toml, pixi.lock, .readthedocs.yml
• _data/, _includes/, _posts/
• vendor/, .pixi/

Open questions

• Should we take this opportunity to redesign the homepage with a VitePress hero layout (like zarrs.dev), or do a 1:1 content migration first?
• Should the Reveal.js slide decks be kept as-is in public/slides/, or converted/dropped?
• Do we want to continue using Google analytics?

[maxrjones]

@zarr-developers/steering-council would you be willing to review this proposal as the website content managers? I'd be glad to help with the migration if the idea is approved

[sanketverma1704]

Thanks for this proposal, Max!
I think it's a great idea to move to anything but Jekyll. It's been a pain to maintain Jekyll over the years, and we could definitely use VitePress.

Long term goal: If we can also merge https://zarr.dev/community-calls/ and https://zarr.dev/zeps/ and bring them under a single repo, it'd awesome!

Happy to drop in and help here and there! ;)

[normanrz]

Hi @maxrjones, this looks like a great proposal! We are happy to approve moving to VitePress.

Should we take this opportunity to redesign the homepage with a VitePress hero layout (like zarrs.dev), or do a 1:1 content migration first?

I would be happy with either option. The VitePress hero layout looks a lot more modern, though.

Should the Reveal.js slide decks be kept as-is in public/slides/, or converted/dropped?

I would be fine with keeping the slide decks as PDF-only.

Do we want to continue using Google analytics?

While I think keeping analytics is useful, I don't think it is a must. Switching out Google analytics for a less privacy-intrusive system/provider would also be a welcome option.