← All workBalaji SankarCase study 02 / 12
B2B SaaS / subscription billing2024-25

ChargebeeDocs

I rebuilt a subscription-billing leader’s product documentation to move it off a proprietary markup and a Java build onto a modern React site. The heart of it is a migration compiler that turns legacy docs into validated MDX.

Case study by Balaji Sankar · Updated October 2026

Client

Chargebee

Role

Frontend lead / full-stack on the docs rebuild

Timeline

2024-25

Stack
Next.js 14ReactTypeScriptMDXunified / remark / rehypeBabelcheerioMDXEditorGitHub APITailwind CSS
Outcomes
4,000+

Docs pages generated, each MDX-validated

5

Product doc sets plus the knowledge base on one site

✦

Every legacy URL mapped to its new home by the same pipeline

01 / 09The opportunity

Why did it need to exist?

The issue
  • Docs written in a proprietary bracket-tag markup
  • A Java and Ant build only engineers could run
  • Separate doc sets with their own navigation rules
  • Every URL and ranking had to survive the move
The solution
  • A compiler that turns the markup into valid MDX
  • One Next.js site for every product line
  • Sidebars, versions and redirects generated together
  • A GitHub-backed editor writers use in the browser
02 / 09The challenge

What made it hard?

The docs had grown up on a home-grown stack: content written in a custom bracket-tag markup with dozens of tags, compiled to HTML by a Java and Ant build, and split across separate repositories for billing, payments, retention, revenue recognition, receivables and a large knowledge base.

Every product had its own build, versioning and navigation rules, and only people who knew the markup could change anything safely. The goal was to move all of it without losing a page, a link, a version or a search ranking - and without asking the docs team to hand-convert thousands of articles.

03 / 09Approach

How did I approach it?

01

Treat it as a compiler problem

Instead of a one-off find-and-replace, I built a Node pipeline: read each product’s YAML index, parse the legacy markup with a set of small tag parsers, run the result through remark and rehype to turn embedded HTML into valid JSX and repair malformed markup, then format with Prettier. It can be re-run as legacy content keeps changing, so no big-bang cutover was needed.

02

Validate before writing

Every generated page is compiled with the MDX compiler before it is written. Failures go to per-product error reports so they get fixed at the source instead of breaking the site build.

03

Carry structure and SEO across

The same run emits sidebars, knowledge-base categories and a full redirect map from old URLs to new ones, so links and search traffic land in the right place and can’t drift from the content.

04

One site for every product

A Next.js App Router site where product, version and page all resolve from the route, with a component library the compiled MDX maps onto. Adding a product is content and config, not a new site.

04 / 09Key decisions

Which calls shaped it?

(01)

A compiler, not a one-off conversion

Problem

Content kept changing during the transition, so a single find-and-replace would go stale immediately.

Decision

I built a repeatable parse, transform, validate and emit pipeline that can be re-run whenever the legacy content changes.

Outcome
  • No big-bang cutover needed
  • Fresh output on every run
  • Fixes made once in the compiler
(02)

Validate every page before writing it

Problem

One malformed page can break an entire MDX site build.

Decision

Each generated page is compiled with the MDX compiler before it is written, and failures are logged per product.

Outcome
  • Every page on the site is MDX-validated
  • Errors fixed at the source
  • Site builds stay green
(03)

Generate structure with the content

Problem

Hand-maintained sidebars and redirects drift away from the pages they describe.

Decision

Sidebars, knowledge-base categories and the full old-to-new redirect map come out of the same compiler run.

Outcome
  • Links and navigation cannot drift
  • Old URLs land on the right page
  • One run updates content and structure
05 / 09What I built

What did I build?

Developer documentation platform
Developer documentation platform1 / 3
  • (01)

    Tag-by-tag parsers for steps, callouts, wells, screenshots, image cards, video embeds, internal and API links, template variables and knowledge-base categories.

  • (02)

    Compile-time MDX validation with per-product error reports.

  • (03)

    Redirect maps and sidebars generated in the same run as the content - a zero-loss URL strategy.

  • (04)

    Version picker and banners, nested sidebar, breadcrumbs, responsive drawer navigation and docs feedback, all from one codebase.

  • (05)

    An in-browser docs editor on MDXEditor with live preview and source diff, wired to GitHub so writers can publish to a branch without a terminal.

06 / 09Foundation

What is it built on?

Repeatable over clever

A pipeline you can re-run beats a perfect one-off conversion.

Lose nothing

Every page, version, link and ranking has to make the move.

Writers own the content

Routine updates should not need an engineer or a terminal.

Compiler
Node.jsunified / remark / rehypeSmall tag parsersMDX compiler
Docs site
Next.js 14 App RouterReactTypeScriptMDX
Components
Notes, warnings and stepsImage cards, video and tables
Editing
MDXEditorGitHub API branch publishing
07 / 09Delivery

How was it delivered?

  1. Phase 1

    Markup inventory

    Catalogued every legacy tag, variable and link type across the product doc sets.

  2. Phase 2

    Tag parsers and pipeline

    Small parsers per tag, then a remark and rehype pipeline that repairs HTML into valid JSX.

  3. Phase 3

    Validation and structure

    MDX compilation before writing, per-product error logs, and generated sidebars, knowledge-base categories and redirects.

  4. Phase 4

    Docs site

    A Next.js 14 App Router site with a version picker, nested sidebar and a shared component library.

  5. Phase 5

    In-browser editor

    An MDXEditor-based editor with live preview that publishes to GitHub branches through the GitHub API.

08 / 09Reflection

What did I learn?

01

Treat content as code

Seeing the migration as a compiler problem made it testable and repeatable.

02

Validation saves builds

Catching bad pages before they reach the site kept the team moving.

03

Structure belongs with content

Generating redirects and sidebars in the same run removed a whole class of broken links.

09 / 09FAQ

Questions about this project

What did Balaji Sankar build in the Chargebee Docs project?
I rebuilt a subscription-billing leader’s product documentation to move it off a proprietary markup and a Java build onto a modern React site. The heart of it is a migration compiler that turns legacy docs into validated MDX.
Who was the client?
Chargebee, in B2B SaaS / subscription billing.
What was the hardest part?
The docs had grown up on a home-grown stack: content written in a custom bracket-tag markup with dozens of tags, compiled to HTML by a Java and Ant build, and split across separate repositories for billing, payments, retention, revenue recognition, receivables and a large knowledge base.
What was his role?
Frontend lead / full-stack on the docs rebuild.
What technology was used?
Next.js 14, React, TypeScript, MDX, unified / remark / rehype, Babel, cheerio, MDXEditor, GitHub API and Tailwind CSS.
What were the results?
4,000+ docs pages generated, each MDX-validated, 5 product doc sets plus the knowledge base on one site and Every legacy URL mapped to its new home by the same pipeline.

Have a project like this?

Tell me what you’re building or what’s broken. I’ll tell you straight whether I’m the right person for it.

Next caseVehicle platform / dealer operations2026Vehicle Dealer Hub→