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
Docs pages generated, each MDX-validated
Product doc sets plus the knowledge base on one site
Every legacy URL mapped to its new home by the same pipeline
Why did it need to exist?
- 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
- 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
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.
How did I approach it?
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.
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.
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.
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.
Which calls shaped it?
A compiler, not a one-off conversion
Content kept changing during the transition, so a single find-and-replace would go stale immediately.
I built a repeatable parse, transform, validate and emit pipeline that can be re-run whenever the legacy content changes.
- No big-bang cutover needed
- Fresh output on every run
- Fixes made once in the compiler
Validate every page before writing it
One malformed page can break an entire MDX site build.
Each generated page is compiled with the MDX compiler before it is written, and failures are logged per product.
- Every page on the site is MDX-validated
- Errors fixed at the source
- Site builds stay green
Generate structure with the content
Hand-maintained sidebars and redirects drift away from the pages they describe.
Sidebars, knowledge-base categories and the full old-to-new redirect map come out of the same compiler run.
- Links and navigation cannot drift
- Old URLs land on the right page
- One run updates content and structure
What did I build?

- (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.
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.
How was it delivered?
- Phase 1
Markup inventory
Catalogued every legacy tag, variable and link type across the product doc sets.
- Phase 2
Tag parsers and pipeline
Small parsers per tag, then a remark and rehype pipeline that repairs HTML into valid JSX.
- Phase 3
Validation and structure
MDX compilation before writing, per-product error logs, and generated sidebars, knowledge-base categories and redirects.
- Phase 4
Docs site
A Next.js 14 App Router site with a version picker, nested sidebar and a shared component library.
- Phase 5
In-browser editor
An MDXEditor-based editor with live preview that publishes to GitHub branches through the GitHub API.
What did I learn?
Treat content as code
Seeing the migration as a compiler problem made it testable and repeatable.
Validation saves builds
Catching bad pages before they reach the site kept the team moving.
Structure belongs with content
Generating redirects and sidebars in the same run removed a whole class of broken links.
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.