In May 2026, gihyo.jp reported that Vercel Labs proposed "MDXG," a draft specification defining Markdown display and interaction experiences. This initiative adds a "User Experience (Gestures)" layer to the MDX extended Markdown specification, defining as formal specifications such features as code block tab switching, expandable blocks, LLM diff viewing, and interactive elements.
This proposal resonates most strongly in the area of "stably rendering LLM-generated Markdown as a user interface." When building documentation platforms based on Astro, Next.js, or Notion across our custom projects, the reality has been that "Markdown rendering rules" were implemented inconsistently for each individual client. Standardizing MDXG has the potential to radically eliminate this "reinvention of the wheel" in custom development.
Why "Markdown UI standardization" is needed now
| Status | Traditional | After MDXG proposal |
|---|---|---|
| Code block display | Custom implementation | Standard component |
| LLM diff display | Proprietary implementation per company | Defined by specification |
| Tab switching | Proprietary syntax per company | Unified by specification |
| Collapsible blocks | Hardcoded details/summary | Standard component |
| Multilingual switching | Hardcoded i18n keys | Expressed via data attributes |
Particularly when "rendering LLM output in Markdown," broken formatting has been an area where different companies have repeatedly run into the exact same bugs across chat UIs, documentation, and internal wikis. MDXG attempts to solve this problem at the specification level.
Four design principles for redesigning documentation platforms in custom development
Principle 1: Separate "Markdown is the spec, UI is the implementation"
We clearly separate the core Markdown text from the UI extensions defined by MDXG. We adopt an architecture where Markdown text is stored in GitHub, Notion, or a wiki, while the MDXG renderer is implemented on the site side. This allows the content storage location and the display engine to evolve independently. This design more rigorously operationalizes the "boundary between content and site" discussed in Integrating Astro with Cloud Build.
Principle 2: Ensure "reproducibility" in LLM output renderers
Because there is no guarantee an LLM will return identical Markdown for identical inputs, invalid nesting and broken tabs must be gracefully handled on the MDXG renderer side. A fail-soft implementation is essential.
Principle 3: Bind backend editors and frontend renderers with the "same contract"
If editors on the Notion, wiki, or GitHub side do not support MDXG extensions, a discrepancy arises between "what can be written" and "what can be displayed." In custom development, we embed an MDXG parser into the editor side to guarantee preview consistency.
Principle 4: Guarantee accessibility at the specification level
Tabs and collapsible blocks require mandatory keyboard navigation and screen reader support. Standard MDXG components lock in aria attributes at the specification level, reducing the labor cost of accessibility audits.
Four phases to build in custom development
Phase 1: Inventory of existing documentation platforms (2 weeks)
We take inventory of the Markdown extensions used across internal wikis, client-facing documentation, and product help centers, estimating the migration cost to MDXG.
Phase 2: Implementation of MDXG renderer (4 weeks)
We implement an MDXG specification-compliant renderer in Astro, Next.js, or Remix. We provide a baseline guarantee for four features: code blocks, tabs, LLM diffs, and collapsible blocks.
Phase 3: Migration of existing documentation (4 to 6 weeks)
We rewrite existing proprietary extensions into MDXG syntax, executing the migration through automated conversion scripts combined with visual reviews.
Phase 4: Integration with LLM output writers (3 weeks)
We design system prompts so that the output conforms to the MDXG specification for Markdown generated by Claude and GPT-5, and then pair this with a fail-soft renderer before rolling it out to production.
Standard technology stack set for custom development
| Layer | Recommended technology | Alternative |
|---|---|---|
| MDX foundation | MDX 3 + remark / rehype | markdown-it + plugins |
| MDXG renderer | Astro Content Collections / Next.js MDX | Docusaurus |
| Editor | TipTap + MDX extension | Lexical |
| Code syntax highlighting | Shiki | Prism |
| Diff display | diff2html | jsdiff |
| Accessibility audit | axe-core | Pa11y |
| LLM output validation | Schema validation with Zod | JSON Schema |
By combining this with Vercel Open Agents — Custom Maintenance Services or Vercel Costs × Bot Defense — Custom Web Hosting Services, we can package as a client offering a "documentation infrastructure completed entirely within the Vercel ecosystem."
Which projects it fits best
| Suited projects | Benefit |
|---|---|
| Product help / API documentation | Unified code blocks / tabs |
| Internal knowledge wiki | Automated rendering of LLM outputs |
| Developer manuals | Highlight updates with diff display |
| Multi-client SaaS documentation | Absorb client-specific extension diffs |
| AI chat UI | Stable display of LLM output Markdown |
Five clauses to include in custom development contracts
| Clause | Details | What the client should verify |
|---|---|---|
| MDXG specification compliance scope | Which extensions to implement | Handling unfinalized specification elements |
| Responsibility for migrating existing documents | Division between custom development team and client | Liability for migration oversights |
| Quality assurance for LLM output | Scope of fail-soft support | Liability for broken rendering |
| Accessibility compliance | WCAG level | Alignment with legal requirements |
| Tracking future specification changes | Monthly / quarterly tracking | Scope and cost of modifications |
Four common pitfalls
Pitfall 1: Deploying an "in-progress specification" to production
As of May 2026, MDXG remains at the draft specification stage. We anticipate on day one of design the risk of breaking specification changes, always inserting an abstraction layer.
Pitfall 2: Delayed support on the editor side
When Notion or Confluence lacks support for MDXG extensions, a gap opens between "those who write" and "those who read." We prepare workarounds using comment syntax + preprocessors.
Pitfall 3: Production displays crashing due to LLM output instability
An implementation where the entire page crashes the moment an LLM emits broken MDXG is unacceptable. We incorporate graceful degradation with paragraph-level fail-soft logic that "degrades only the broken portion to plain text."
Pitfall 4: Retrofitting accessibility requirements
Retrofitting accessibility onto expandable blocks and tabs requires major overhaul work. We integrate axe-core into CI from day one to immediately detect specification violations. This reflects the philosophy of guaranteeing quality during the CI stage, much like our approach in Troubleshooting Astro Cloud Build Errors.
Summary — "Markdown is the spec, UI is the implementation" becomes the standard
The Vercel Labs MDXG proposal elevates Markdown from a "text format" to a "UI specification." We have entered an era where the "reinventing of the wheel" repeatedly seen in custom development can be drastically reduced through MDXG-compliant renderers combined with fail-soft design.
If you have concerns such as "LLM-generated documentation displays unstably" or "We want to unify the experience between internal wikis and public documentation," please feel free to reach out via our contact form.
