feat: improve AcceptMarkdown support#209
Conversation
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
superwall-docs-staging | 181f40a | Commit Preview URL Branch Preview URL |
Jun 06 2026, 12:30 AM |
dcrawbuck
changed the title
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
dcrawbuck
force-pushed
the
duncan/sw-5396-docs-full-acceptmarkdowncom-support
branch
from
35ee720 to
3bf524c
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3bf524c276
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| return buildMarkdownRouteResponse(includeBody ? body : null, slugs); | ||
| } | ||
|
|
||
| export const Route = createFileRoute("/{$}.md")({ |
There was a problem hiding this comment.
When the alternate URL is for a nested doc such as /docs/ios/quickstart/install.md, this route will not handle it: the generated route tree for this file is /{$}.md, i.e. a single path segment with a .md suffix, while TanStack splats are the /$ segment captured in params._splat. Since shouldBypassLLMRewrite now skips all .md paths, those nested alternates fall through to the normal docs splat as ios/quickstart/install.md and 404 instead of returning the page markdown. Please make the .md/.mdx routes catch nested paths before the suffix, or stop bypassing the existing markdown rewrite for direct suffix URLs.
Useful? React with 👍 / 👎.
| rehypeCodeOptions: isDevelopment ? false : undefined, | ||
| remarkPlugins: (existing) => [ | ||
| remarkImagePaths, | ||
| remarkMarkdownImageMap, |
There was a problem hiding this comment.
For pages whose images come from <include>d shared MDX, this plugin runs before remarkInclude, so those included image nodes are not added to markdownImageMap even though they are present in the processed markdown later. For example, content/docs/ios/guides/advanced/observer-mode.mdx includes content/shared/observer-mode.mdx, which contains /images/om_transactions.png; that page's markdown alternate can be left with an unresolved __img... placeholder instead of the restored image URL. Move the map collection after include expansion or otherwise collect images from included content.
Useful? React with 👍 / 👎.
| headers: { | ||
| Vary: "Accept", | ||
| }, |
There was a problem hiding this comment.
When a browser on another origin fetches a canonical docs URL with Accept: text/markdown, this 307 is part of the CORS redirect chain but only includes Vary. The final markdown route sets Access-Control-Allow-Origin: *, yet the browser can block before following it because the redirect response itself lacks that header. Add the same CORS header to the negotiation redirect so cross-origin consumers can use the advertised AcceptMarkdown URL, not just the direct .md URL.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 04d16ec766
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| }; | ||
|
|
||
| const htmlImagePlaceholderPattern = /<img\b([^>]*?)\bsrc=["']__img(\d+)["']([^>]*)\/?>/g; | ||
| const markdownImagePlaceholderPattern = /(!\[[^\]]*]\(\s*)<?__img(\d+)>?(\s*\))/g; |
There was a problem hiding this comment.
When a markdown image includes a title, the processed placeholder can be emitted as , but this pattern only matches placeholders followed immediately by ), so those images are left as __img… in the .md alternate. Several existing docs use titled images, including content/docs/ios/quickstart/install.mdx, so those pages can expose unresolved placeholders instead of usable image URLs.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 181f40a. Configure here.
| const placeholder = getImagePlaceholder(node); | ||
| const url = getImageUrl(node); | ||
| if (placeholder && url) imageMap[placeholder] = url; | ||
| }); |
There was a problem hiding this comment.
JSX img tags omitted from map
High Severity
remarkMarkdownImageMap only records markdown image nodes and JSX img elements that already use __img placeholders plus a separate URL. Real pages use <img src="..."> (for example under Agents), so markdownImageMap stays empty while processed markdown still contains __imgN tokens, and restoreImagePlaceholders leaves broken placeholders in exported Markdown.
Reviewed by Cursor Bugbot for commit 181f40a. Configure here.
1 participant
This adds AcceptMarkdown-compliant content negotiation for docs routes, including Fumadocs-based q-value negotiation,
Vary: Accept, alternate/canonicalLinkheaders, and 406 responses for unsupported media types.It adds Markdown alternate URL helpers plus root and nested
/llms.mdx/docsroutes so/docs/,.md,.mdx, and canonical docs URLs all resolve to Markdown where appropriate.It switches processed Markdown generation to Fumadocs placeholder rendering for common MDX components, making Markdown cleaner for agents while keeping HTML pages unchanged.
It adds tests for negotiation and rewrite behavior; local validation covered
bun test,bun run build:cf, curl checks against local dev, and agent-browser checks.Note
Medium Risk
Changes global request middleware and routing for all
/docstraffic (redirects, 406/404, headers); regressions could affect crawlers, copy-markdown flows, or CDN caching keyed onVary: Accept.Overview
Adds AcceptMarkdown-style behavior for docs:
Acceptnegotiation (including q-values and legacytext/plain/text/x-markdown),Vary: Accept,Linkalternate markdown URLs on HTML responses, and 406 when a known docs URL gets an unsupportedAccept. Markdown-preferred canonical URLs 307 to*.md(overview to/docs/llms.mdx/docs/).Introduces shared
{$}.md/{$}.mdxand/llms.mdx/docshandlers (GET/HEAD) with canonical HTMLLinkheaders, and wires doc pages tobuildMarkdownAlternatePathfor copy/view actions and<link rel="alternate">.Improves agent-facing markdown: Fumadocs processed-markdown options (MDX placeholders → readable markdown),
remark-markdown-image-map+ passthrough export, andgetPageMarkdownTextthat expands placeholders, resolves image URLs, and prepends title/description.Docs copy in vibe-coding notes the
.mdURL suffix; asset path normalization moves todocs-asset-path. Tests cover negotiation/rewrites and the image-map remark plugin.Reviewed by Cursor Bugbot for commit 181f40a. Bugbot is set up for automated code reviews on this repo. Configure here.