From Jekyll to Rspress: How AI Helped Us Rebuild Coveo Docs

This summer, a team of three developers at Coveo evaluated four documentation platforms, picked one, and converted more than 5,000 articles to it. They had assistance: AI coding agents built the prototypes, helped write the conversion pipeline, and, most importantly, worked through the issues our quality reports flagged, iterating on local builds until they could open pull requests. Without these agents, a project of this scope would have taken such a small team far longer.

The result will be a new documentation site, built on Rspress, a static site generator powered by the Rust-based Rspack bundler. It replaces the Jekyll site that has carried our documentation for years. It will be live at beta.docs.coveo.com in a few days and become docs.coveo.com a few weeks after that.

Here’s why we did it, how AI changed the way we chose a platform and moved our content, what we got wrong, and the lessons we’d pass on to teams planning a similar move.

Why Replatform?

Jekyll has served us well. A decade later though, it’s starting to show its age.

Aging infrastructure. Jekyll is a Ruby-based static site generator, and our setup has collected years of custom plugins, includes and conventions. Creating a new feature often felt like working around the platform. Also, only our team used Ruby at Coveo, which reduced potential for collaboration. Lastly, because the Jekyll ecosystem is less active, features that come for free as ready-made packages in more recent Node.js platforms often took extra work to build for Jekyll.

A slow feedback loop for writers. A local rebuild took three to four minutes. Hot reload worked only for the simplest changes, and even then took about 20 seconds. Substantial code changes and changes to reused content weren’t picked up at all, requiring manual rebuild. In short: contributors were losing time.

Poor performance. Our static site was slower than it needed to be. The page templates didn’t follow modern web practices, and render-blocking assets slowed down page display.

Information split across sites. Over time, our documentation spread out. To document the Coveo Atomic and Headless libraries, we leveraged specialized tools and generated custom sites for them. Those sites had their own navigation, search, and look. A reader who wanted to go from a concept to the matching reference docs had to cross a site boundary to do it. This worked, but it wasn’t ideal, and we wanted to abstract the complexity away from readers. Unifying the documentation experience under the Jekyll site would have been possible but difficult due to the aging infrastructure mentioned earlier.

Complex AsciiDoc. Much of our content was written in AsciiDoc, and not in one flavor. As different authors contributed at different times, different conventions were adopted: how lists were nested and continued, how admonitions and code callouts were written, how includes and variables were used. We were getting further and further away from plain markdown, which is more standard in docs-as-code setups. We were effectively taking on technical debt as time went on.

Choosing a Platform With AI-Built Prototypes

We evaluated four candidates: Rspress, Astro, Astro Starlight and Fumadocs.

With AI coding agents, we built a working proof of concept on each platform within days and estimated the work for every requirement it didn’t cover out of the box.

We also tested with real content. Instead of a “hello world” site, each prototype built a realistic slice of documentation, about 6,000 files. That gave us a representative baseline for build time, dev-server startup, and scalability.

The two Astro options built fastest: a cold production build of the full set took 43 seconds with Astro Starlight and 52 seconds with bare Astro. Rspress took 1 minute 28 seconds, and Fumadocs ran past 20 minutes without completing.

Fumadocs had great authoring features but didn’t seem like it could accommodate our scale. Bare Astro was fast but would have meant building sidebars, a table of contents, search, and theming ourselves. Starlight was the closest contender, with the fastest builds and the most built-in features.

We chose Rspress for three reasons:

• Authoring experience. It ranked best for writers who aren’t developers, and had nice built-in dead-link and dead-image checks and clear error messages.
• Portability. Rspress uses standard React components and unified remark/rehype plugins rather than proprietary formats and APIs. If we ever move again, most of our work comes with us.
• Enough speed. Its dev server started in 20 seconds, hot reload was close to instant, and a 45-second gap with Starlight’s cold build was a small price for more control and a friendlier writing setup.

How Agents Fixed Thousands of Converted Pages

Choosing a platform was the easy part. Moving more than 5,000 articles was harder, especially since we didn’t want to block writers from their work. Our target was a conversion pipeline we could run reliably for weeks, during the transition to the new Rspress site, while writers could keep working in the Jekyll site without a prolonged content freeze. This is where AI agents made the biggest difference.

Content complexity. Our docs include thousands of articles written by a dozen authors over a decade, along with generated reference content, glossaries, release notes and redirects that go back years. Every page needed to arrive intact, every old URL needed to keep working, and every internal link needed to point to the right place. On top of our complex, non-standard AsciiDoc, the Jekyll site had its own custom extensions, such as include fragments, audience tags, variable substitution, and search metadata.

A custom conversion pipeline. A generic AsciiDoc-to-Markdown tool wasn’t going to work. We built a dedicated conversion pipeline that turns the Jekyll sources into MDX. It handles each of our custom constructs, resolves includes and variables, maps old slugs to new routes, optimizes images, and post-processes glossary and API reference links. The pipeline is covered by tests, and we can run it again whenever the source changes.

Automated quality checks. To determine how accurately conversion works, we built two complementary checks. A source-level comparison matches each converted MDX file against its original AsciiDoc. A content-parity check compares every rendered page on the new site with its counterpart on the old one and scores how similar their text is. That turned “does the new site look right?” into a number we could track, and a report that said exactly what to fix.

The Loop: People Check, Agents Fix. The biggest gain came from pairing agents with those reports. We ran the full checks and launched agents on issues.

An agent would take a reported issue, or a whole class of them, and fix the tooling: the converter, the federation logic, or a helper such as link rewriting. It then built the affected pages locally and inspected the result, iterating until the reported problem was gone. Only then did it prepare the change for one of us to review. Many fixes came from the lowest-scoring pages, for example list items that lost their nesting or blocks that ended up attached to the wrong step.

Fix the tooling, never the pages. Agents didn’t hand-edit converted content. Every fix went into the converter, the federation logic or a helper, so it applied to the whole corpus the next time the pipeline ran, and the pipeline stayed rerunnable for the duration of the migration.

Human reviews and checks. The full checks took hours to run and provided enough work that we didn’t need to run them very often. A few times a week sufficed. Also, human judgement was useful to launch agents on the most valuable fixes, and to spot deeper structural issues. Especially at the beginning of the project, thorough review was needed, because decisions had to be made by experienced writers. What list format do we want to adopt going forward? Do we support includes in lists? What about lists in includes, and if so, how? What about admonitions?

Where our time went. Instead of fixing issues one by one, we spent it reviewing the batches of changes agents prepared and launching agents onto the next set of most important issues.

The long tail. Where this workflow shone the most was towards the end, to address the long tail of corner cases; thousands of small, idiosyncratic issues, sometimes occurring only on a handful of pages. At that point, human reviews were often very quick because all the big architectural decisions had been made, and agents made few mistakes. We could let them run during evenings or weekends and get good results when we got back to our desks the next morning. Over a weekend, an agent could complete work that would have taken a human weeks to do.

The result. In the end, we achieved a reliable conversion pipeline that uses the Jekyll site to update the Rspress site daily, while a team of 10 writers keeps authoring and editing articles in the former. As we roll out the new site, we’re confident that both the platform and the content will hold up to our quality standards.

What We Got Wrong

AI made this migration possible for a team our size, but it didn’t make it fully predictable. We’ll learn more lessons as we wrap up this project, but here are two takeaways we can already share.

We didn’t sufficiently analyze the corpus for all usage patterns. With a dozen writers active in the repo for almost a decade, no one had all the usage patterns in mind, and we discovered many, many of them during the conversion, despite a preliminary agent-aided investigation.

• How are lists, admonitions and includes nested?
• Are they nested recursively?
• How do they parse in markdown versus in asciidoc?

In hindsight, we’d have spent more agent time up front exploring the Jekyll site to map all such patterns, before converting anything in bulk.

Our benchmarks left out file complexity and our own plugins. We stress-tested every platform at close to 6,000 pages, but these pages didn’t have includes, and none of these prototypes ran the custom plugins we later wrote, such as content includes, or had the same page complexity that we encountered in practice. Once that happened, build times grew substantially. The migration required frequent rebuilds, slowing us down. Agents often had to rebuild the entire site to run checks while iterating on fixes, so the longer the build times, the longer it took agents to put up fixes. In retrospect, we would benchmark with more complex articles, and perhaps even prototype plugins. It would have let us better estimate the work required to get the content conversion up to the target standards.

What Readers and Writers Get

The most visible changes for readers are speed and a single, unified site. The bigger change is behind the scenes: writers can now update the docs faster, and docs that are faster to update stay more accurate and more complete.

A faster feedback loop for writers. The dev server starts in seconds, and writers see their changes almost as soon as they save, instead of waiting or needing to manually trigger a reload. Built-in dead-link and dead-image checks also catch mistakes at build time, without needing to wait for a CI check.

One site for all our docs. Reference documentation for Headless, Headless React, Atomic and Relay, along with our REST API references, now lives on docs.coveo.com instead of separate sites. A federation pipeline pulls each source from npm, GitHub releases, TypeDoc and OpenAPI, detects changes, and keeps the pages current. Readers get one site, one navigation and one search.

Before and after:

Search and recommendations powered by Coveo. As before, search and article recommendations on docs.coveo.com run on Coveo. The new site also adds a ⌘K command palette built with Coveo Headless.

Speed. Rspress outputs lean static HTML with modern bundling and code splitting, so pages load and become interactive faster. Every feature of the Jekyll site carried over, often in smoother ways, such as dark mode and responsive layouts. Here are some before and after metrics:

Semantic URLs. URLs now describe their content. Instead of opaque numeric page IDs, you get paths that tell you where you are before the page loads, which helps readers, search engines, and anyone sharing a link. Slugs are still supported, whenever they are needed.

Try the New Docs

The new site will be publicly available at beta.docs.coveo.com in a few days, while docs.coveo.com keeps serving the current site. A few weeks later, the new site moves to docs.coveo.com. Every old URL redirects to its new home, so your bookmarks and links keep working.

The migration gives us a solid foundation. With a modern stack, a fast feedback loop, and all of our docs in one place, we can spend less time fighting tooling and more time on what matters: clear, accurate, helpful documentation.

This replatforming is a first step towards making significant UX and content architecture improvements to docs.coveo.com. Stay tuned.