fix(portal): keep the encoding a page slug carries

[sohail2721]

Closes apimatic/apimatic-io#2270.

The bug

apimatic portal generate failed outright on a spec whose operationId carries a space:

Error: Failed to fetch /api/openapi/portal-artifacts-generation---async/Generate Portal Artifacts Async: Not Found
    at @tanstack/start-plugin-core/dist/esm/prerender.js:81:13

Fumadocs names an operation's page after its operationId verbatim — slugify reaches tag folders and webhook names, never this (fumadocs-openapi/dist/utils/pages/preset-auto.js):

if (algorithm === "v2" && operation.operationId) return operation.operationId;

and then encodes each slug segment as it builds the page (fumadocs-core/dist/source/plugins/slugs.js):

slugs.push(encodeURI(name));

So the page is filed under Generate%20Portal%20Artifacts%20Async. Both routes built their slugs straight from the splat, which the router hands back already decoded:

const slugs = params._splat?.split('/').filter((segment) => segment.length > 0) ?? [];

source.getPage then compared a decoded segment against an encoded one, missed, and threw notFound(). The prerenderer turns that into a failed build; portal serve does not prerender, so there the page simply 404s while the sidebar keeps linking to it.

The change

One function owns the spelling the two sides have to agree on, beside the other slug helpers in shared.ts:

export function slugsFromSplat(splat: string | undefined): string[] {
  return (splat ?? '')
    .split('/')
    .filter((segment) => segment.length > 0)
    .map(encodeURI);
}

Both routes read their slugs through it, so neither splits a splat of its own, and head() uses it too — a page's canonical link and og:url now carry the same address sitemap.xml publishes. Once operation pages are named so their slugs need no encoding (apimatic/apimatic-io#2271) only the encodeURI goes; the helper stays.

Dropping the empty segments is new for {$}.md.ts, which did not filter before: /guides/.md and /.md now serve Markdown where they used to 404.

encodeURI, not encodeURIComponent. They differ on &, +, =, @ and more, and Fumadocs uses encodeURI; encoding harder than it did would miss the very pages this is meant to find. encodeURI is the identity on an ordinary slug, so nothing else moves.

Not a regression from #387

That PR passes a slugify identical to Fumadocs' own default, and an operation's page name never went through slugify in either version. What changed is that the step became reachable: this build used to fail earlier, in the TypeScript artifacts lane (apimatic/codegen-v2#517), and only got this far once that fix was deployed.

Tests

test/portal-template/page-slugs.test.ts, six cases.

slugsFromSplat on its own: empty segments dropped, an ordinary slug untouched, and the encoding pinned to Fumadocs' — a space and a non-ASCII character encoded, & left alone, which is what separates encodeURI from encodeURIComponent and is the line a future edit is most likely to cross.

Then a real section built by openApiSection from a spec whose operationId is List All Pets, decoded the way the router decodes it, and looked up:

• found at its page address;
• found at its .md address — the router strips .md before the handler sees the splat, so the same segments serve both;
• not found when the splat is used as it arrives — the negative control, which fails without this change and is the regression this PR closes.

These call encodeSlugs and getPage directly rather than loading either route, so they do not fail if a route stops encoding. A build fixture that would is apimatic/apimatic-io#2272.

Full suite: 1476 passing, 0 failing, 46 pending. tsc --noEmit clean on both projects, eslint . exit 0.

Left for follow-up

• apimatic/apimatic-io#2271 — the navigation still compares a decoded pathname against an encoded slug, so nothing is marked active on such a page; and encodeURI leaves ? and # alone, so an operationId like get?pets still fails the build. Naming operation pages so they never need encoding closes both, and makes encodeSlugs unnecessary.
• apimatic/apimatic-io#2272 — a test that fails if either route stops encoding.

🤖 Generated with Claude Code

[saeedjamshaid]

The diagnosis is right and this fixes the #2270 build. Thanks for tracing it into Fumadocs' slugs.js.

Two changes before merge, both inline: build pageUrl in head() from the same helper, and drop the .md from the Markdown test's splat. The other two inline comments (nav active state, a route-level test) can be follow-up tickets if you'd rather keep this PR small. Please file them either way.

Also:

• Dropping empty segments changes the .md route: /guides/.md now serves the guides page's Markdown and /.md the home Markdown, where both used to 404. Harmless, but it's a change nobody asked for.
• encodeURI leaves ? and # alone, so an operationId like get?pets still gives a page URL with a query string and fails the build the same way. Naming operation pages so they never need encoding would close that case and the nav one together.
• Nit: urlOf() rebuilds the bundle and loader in every case, and beforeEach rewrites the same spec. before()/after() would do.

[saeedjamshaid]

Thanks, this all looks good. Sorry, my .md note read like a request to revert, and it wasn't. One small follow-up before I approve: could we go back to a single slugsFromSplat in shared.ts, shared by both routes?

export function slugsFromSplat(splat: string | undefined): string[] {
  return (splat ?? '')
    .split('/')
    .filter((segment) => segment.length > 0)
    .map(encodeURI);
}

• $.tsx: drop pageSlugs and call slugsFromSplat(params._splat) in both the loader and head().
• {$}.md.ts: decodeMarkdownUrl(slugsFromSplat(params._splat)).
• Tests: call slugsFromSplat(decodedSplatOf(url)) instead of copying the route's split('/'), and bring back the empty-segment case.
• Description: update the "each route keeps the splitting it already did" line to match.

This is the part that stays after #2271 (only the encodeURI goes), and it takes the split('/') out of the routes. /guides/.md and /.md serving Markdown is fine.

[sohail2721]

Done in 299b824 — and no need to apologise, reverting it was my call rather than your wording. Glad to have it back as one helper.

slugsFromSplat is restored exactly as you wrote it. $.tsx drops pageSlugs and calls it in both the loader and head(); {$}.md.ts is decodeMarkdownUrl(slugsFromSplat(params._splat)). Neither route splits a splat of its own any more.

Tests call slugsFromSplat(decodedSplatOf(url)) rather than copying the route's split('/'), and the empty-segment case is back — six again.

The description line is updated. It now says both routes read their slugs through the helper, notes that only the encodeURI goes once #2271 lands, and states the .md change plainly rather than leaving it to the reader: /guides/.md and /.md serve Markdown where they used to 404.

Full suite: 1477 passing, 0 failing, 46 pending. tsc --noEmit clean on both projects, eslint . exit 0.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀