docs/solutions/developer-experience/2026-05-27-llm-markdown-routes-should-normalize-md-suffix-before-source-lookup.md
Public markdown links need to keep the .md suffix so agents receive a stable URL like /docs/installation/mcp.md.
Fumadocs page lookup should not receive that suffix. source.getPage(['installation', 'mcp.md']) looks for a page named mcp.md, while the real slug is mcp.
.md links for ChatGPT and Claude./docs/installation/mcp.md could be rewritten to an LLM route./llm/installation/mcp.md requests missed the page because the route passed the raw slug to source.getPage.Normalize only the route params used for source lookup:
export const stripMarkdownSuffixFromSlug = (slug: string[] = []) => {
if (slug.length === 0) return slug;
const last = slug.at(-1);
if (!last?.endsWith('.md')) return slug;
return [...slug.slice(0, -1), last.slice(0, -3)];
};
Keep the public URL builder unchanged. The shared URL should stay /docs/... .md; only the internal lookup slug should become /docs/....
There are two contracts:
.md because that is the user-facing and agent-facing document format.Keeping those contracts separate makes rewritten docs markdown URLs and direct LLM route URLs behave the same way, including localized /cn routes.
Test both entry points:
/docs/installation/mcp.md/llm/installation/mcp.mdFor localized docs, test both localized markdown output and English fallback lookup.