ChargebeeDocs
I moved a subscription-billing leader’s product documentation 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.
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
Thechallenge
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 Iapproached 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 each product’s sidebar, version config 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.
Highlightsworth showing
- (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.
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.