Proposal: Migrate documentation to VitePress

[50rayn]

Hello everyone,

I've been exploring ways to modernize the date-fns documentation website and would like to propose migrating the current documentation stack to VitePress.

Context & Motivation I have been experimenting with a migration locally for the past few days. The goal is to improve the Developer Experience (DX) for contributors and provide a faster, more responsive UI for users.

Many modern documentation sites (like Vitest, Vite, and Reka UI) use VitePress effectively. Moving to this stack could offer us better maintainability and performance out of the box.

Visual Comparison

Here is a side-by-side view of the Homepage. The new design (right) uses a cleaner grid layout and modern typography compared to the current version (left):

Documentation Experience

The readability improvement is even more visible on the documentation pages. The navigation is clearer, and the content hierarchy is improved:

Component Detail (New Look)

I've also focused on making the API references easier to scan. Here is how the closestTo function looks, with clear tabbed code blocks for ESM/CommonJS and structured Argument tables:

Click to see more examples (Getting Started, Tooltips)

Getting Started Page

Improved Tooltips/IntelliSense

Proposed Roadmap

I envision this migration in two phases:

1. Phase 1: Functional Migration (1:1 Port)

   • Migrate the existing content and structure to VitePress.
   • Ensure all current functionality and links work correctly.
   • Focus purely on infrastructure and content parity.

2. Phase 2: UI/UX Improvements

   • Once the base is stable, iterate on the design.
   • Aim for a modern look and feel similar to the Vitest or Vue ecosystem docs.
   • Enhance navigation and search capabilities.

Open Question: VitePress vs. Nuxt While VitePress seems like the ideal fit for static content-heavy sites, I briefly considered a custom Nuxt application (SSR). However, given that our primary need is performant static documentation hosting, VitePress feels like the lighter and more focused tool. I would love to hear the community's thoughts on this.

Next Steps I have a working proof-of-concept locally. If the maintainers are open to this direction, I can polish it up and open a PR or share a preview link for review.

Looking forward to your feedback!

[stuart-haas]

One thing I really like about the original design is the code example on the home page. It's what drew me into using this library to begin with. I think it's a good idea to show users how easy it is to use from the get-go.