feat(mdxish): add new MDXish engine

[maximilianfalco]

	Fix RM-XYZ

Warning

As of 5 Dec 2025 (keeping this to track timeline) SSR for mdxish has been disabled. All contents that are rendered by mdxish will be done client-side. For more context, refer to this thread

🧰 Changes

Context

This PR exports 2 new libraries which provides a new way to render mixed Markdown + MDX content in our application.
This allows customers to flexibly embed MDX inside Markdown without relying on the strict MDX renderer or needing to migrate everything to MDX (which currently causes many errors and requires hours of cleanup)

Important

With the addition of the new libraries, we unfortunately have exceeded the maximum bundle size allowed. Specifically the current bundle size is 762KB and the limit was 750KB, this has been increased to 775KB

Changes

1. mdxish.ts

• Engine to convert a Markdown + MDX string into an HTML AST.
• Based on Greg’s prototype and uses Unified plugins.
• Handles MDX by preprocessing its syntax.
• Additional logic:
  • Reuses existing transformers (e.g., callouts).
  • Adjusts MDX nodes when spacing breaks the AST.
• Custom component handling:
  • Recursively parses inner content.
  • Renames nodes to PascalCase.
  • Includes heuristics to determine whether a tag is a real component vs. an HTML tag.

2. renderMdxish.tsx

• Converts the HTML AST into React JSX components
• Mimics the existing run.tsx behaviour used in production, returns an RMDXModule which contains the content react component, and the table of contents

We also expose another library called mix but this isnt actually used for rendering. This is simply a wrapper around mdxish that returns stringified HTML instead of HAST. This can be useful for testing/development or when we need a stringified version of the HAST.

🧬 QA & Testing

How to Test Locally

To test this new rendering engine directly in the ReadMe app:

• Open two terminals:
  • ReadMe (branch: mdxish-demo)
  • Markdown (this branch)
• Link Markdown to ReadMe:
  • In markdown: npm ci && npm run build
  • In readme: make link-markdown
• Run the ReadMe repo and open any project — it should not crash
• Create docs using mixed Markdown/MDX (via Raw mode) and verify they render correctly
  • You can use the files in tests/lib/mdxish/demo-docs as examples in your editor

Testing In The PR App

We have prepared a PR app that has the new mdxish engine enabled by default for all projects. See it here

Things to Test in Docs

• Built-in ReadMe components
• User-defined components
• Table of contents
• Unclosed tags (e.g., <br>)
• Links, headings, formatting, etc.

📸 Some Screenshots

These screenshots are sample MD/MDX pages that is rendered using the new libraries. All screenshots here and all demo does not have correct validation yet. We purposefuly disabled validation to demo this new engine/library.

[maximilianfalco]

sorry for the re-ping here folks, a lot has changed since the initial review so wanted to double check with everyone 🙏

[rafegoldberg]

A bunch of thoughts/questions for y'all here.

[rafegoldberg]

@eaglethrost​/@maximilianfalco—looks like our magic block tests are throwing an error! 😬 Seems that images are getting wrapped in an extra <p> tag for some reason…

[eaglethrost]

@eaglethrost​/@maximilianfalco—looks like our magic block tests are throwing an error! 😬 Seems that images are getting wrapped in an extra <p> tag for some reason…

Checking!! Weird it's passing on my local...

[rafegoldberg]

@eaglethrost just tried and it's passing for me locally too. I thought it might be because our test runner is using Node v25/NPM v11 (instead of v22/10, which is what I had on my machine.) But even when I use that latest Node/NPM I can't replicate…

Since this is a brand new test only for MDXish, and it works locally, I'm going to skip these unit tests for now. If only so we can see what a full CI run nets us.

[rafegoldberg]

This PR was released!

🚀 Changes included in v11.8.0