@dotdotgod/markdown-render-next

Experimental same-URL HTML/Markdown negotiation for Next.js App Router. Apache-2.0. ESM and TypeScript declarations are included.

Alpha status and requirements

This alpha targets Next.js 16.4.2, React 19.3.1 and Node.js 22. Other versions, Edge runtime, static export and CDN caching are not verified. APIs may change.

Known limitation: Next.js replaces Proxy Vary on HTML responses. Markdown handlers preserve Accept and explicitly declared host fields, but the full HTML/Markdown Vary contract test still fails. This is not a stable or fully compliant release. Keep document responses uncached at every cache layer. The package enforces private, no-store; deployment rules must not override it. Accept: text/markdown alone cannot prevent a cache from returning stored HTML.

Install

In an existing Next.js App Router application:

npm install @dotdotgod/markdown-render-next@alpha

No HTML scraping, template engine, identity service or hosted proxy is included. Routes are registered manually; markdown.ts is not a special Next.js route file.

Minimal public page

Share a loader between the existing HTML page and an explicit Markdown view. Keep the host application's existing root layout.

1. Shared data: lib/content.ts

export function loadHome() {
  return { title: 'Hello', description: 'One URL, two representations.' };
}

2. HTML: app/page.tsx

import { loadHome } from '../lib/content';

export default function Home() {
  const data = loadHome();
  return <main><h1>{data.title}</h1><p>{data.description}</p></main>;
}

3. Markdown: app/markdown.ts

import { escapeMarkdownText } from '@dotdotgod/markdown-render-next';
import { loadHome } from '../lib/content';

export const homeView = {
  load: loadHome,
  render: (data: ReturnType<typeof loadHome>) =>
    '# ' + escapeMarkdownText(data.title) + '\n\n' +
    escapeMarkdownText(data.description) + '\n',
};

4. Internal endpoint: app/markdown-internal/home/route.ts

import { createMarkdownHandler } from '@dotdotgod/markdown-render-next';
import { homeView } from '../../markdown';

export const dynamic = 'force-dynamic';
export const GET = createMarkdownHandler(homeView);
export const HEAD = GET;

Use a routable directory, not an underscore-prefixed private folder. Do not put page.tsx and route.ts at the same public route. Internal URLs are publicly reachable: protected views must authorize direct requests too.

5. Host entrypoint: proxy.ts

Compose this into the host's existing Proxy; never overwrite its authentication or routing logic. The following example registers only the public root page:

import { NextRequest, NextResponse } from 'next/server';
import { markdownProxy } from '@dotdotgod/markdown-render-next/proxy';

export function proxy(request: NextRequest) {
  // Run host policy before representation selection for protected routes.
  if (request.nextUrl.pathname !== '/') return NextResponse.next();
  const target = request.nextUrl.clone();
  target.pathname = '/markdown-internal/home';
  return markdownProxy(request, target);
}

export const config = {
  matcher: [{
    source: '/',
    missing: [
      { type: 'header', key: 'rsc' },
      { type: 'header', key: 'next-router-prefetch' },
      { type: 'header', key: 'purpose', value: 'prefetch' },
    ],
  }],
};

Matcher exclusions protect React navigation; they are not authorization controls. The helper also excludes RSC/prefetch signals. Authenticate at the data boundary. Then run the host's Next dev command and request the same URL:

curl -i -H 'Accept: text/html' http://localhost:3000/
curl -i -H 'Accept: text/markdown' http://localhost:3000/

Authentication and host Vary

A view may provide authorize({ request, params }), returning a verified access grant or a host Response. A Response stops load/render; any other value, including undefined, becomes access. Authorization exceptions return a generic 500. load receives { request, params, access } and returns safe data or a Response. The host owns sessions, token validation, document/tenant permissions and denial responses. A view hook cannot override an earlier host denial. Do not trust client-supplied identity headers or serialize credentials/access contexts.

Declare trusted host Vary fields on the handler when needed:

export const GET = createMarkdownHandler({ ...view, vary: ['X-Content-Language'] });
export const HEAD = GET;

Each entry is an HTTP field name or *. Invalid names fail at construction. The copied list applies to every handler response, including denials and errors. This preserves Markdown fields, not missing HTML fields or unknown Proxy values. No production OAuth provider, trusted Proxy-context bridge or MCP adapter is included.

API and behavior

• negotiate(accept, hasMarkdown?): returns html, markdown, 400 or 406. Missing Accept and equal preference select HTML. q=0 excludes a representation; media-range specificity is respected. Malformed Accept rejects the request.
• varyAccept(headers, additional?): merges Accept and trusted host field names case-insensitively, preserving existing values and respecting Vary: *.
• createMarkdownHandler(view): authorization, negotiation, one load and explicit string/async-string rendering. Export as GET and HEAD; HEAD omits the body. Responses use private, no-store and preserve host rejection status/headers.
• escapeMarkdownText(text): escapes dynamic inline text only. It is not a URL, code-block, HTML or template-source sanitizer. Validate other output contexts.
• markdownProxy(request, target): call after host policy on registered document routes. target is a same-origin internal URL; null registers an HTML-only route. Unregistered paths must pass through in the host Proxy.

Automatic discovery, dynamic/catch-all route mapping, basePath/locales, arbitrary config/Proxy composition and deployment caches need further validation. This package's alpha publication does not certify those integrations.

License

Apache License 2.0. Third-party material retains its own notices.