I'm adapting a React and Next.js site to be more accessible to AI tools and would like to serve content as either text/html, text/markdown, or text/plain depending on the request headers. Should I convert the generated HTML into Markdown, or keep a structured format such as XML or JSON as the single source of truth and render it into HTML or Markdown as needed? I'm especially interested in practical approaches for handling this in a Next.js application.
4 Answers
Content negotiation is a reasonable design: inspect the Accept header and return the requested format, with HTML as the default. For an article-focused site, Markdown can be the source of truth and rendered to HTML for the web. For a data-heavy or component-driven site, use a structured content model and write separate renderers for HTML, Markdown, and plain text instead of trying to reverse-engineer one format from another.
It’s usually better not to treat generated HTML as your canonical content and then convert it back to Markdown. Keep the source in Markdown or a structured format such as JSON, MDX, or a document schema, then render that into HTML for browsers and Markdown or plain text for other clients. Libraries in the unified ecosystem, such as remark and rehype, can help with parsing and conversion.
HTML-to-Markdown conversion is possible and there are plenty of libraries that map headings, links, emphasis, lists, and other elements into Markdown. However, the conversion becomes lossy once your HTML contains interactive widgets, custom components, styling, tables, or JavaScript behavior. Decide which subset of your HTML has a meaningful Markdown equivalent before relying on this approach.
First clarify what the alternate representation is meant to provide. AI systems can generally parse HTML, so converting everything may not be necessary. If the goal is a clean text endpoint, expose the semantic content directly and omit navigation, scripts, styling, and interactive controls. In Next.js, the backend or route handler can choose the representation based on the requested media type, such as text/html or text/plain.
That’s the concern I had: simple articles convert cleanly, but complex application UI does not have an obvious Markdown representation.