refactor(website): Enhance API shortlinks to support staged renames

[Joshua Smithrud (Josmithr)]

The website publishes from main, but it consumes API documentation artifacts from release branches. As a result, documentation cannot normally link to a new or renamed API until the related API changes are released.

ApiLink and PackageLink now support temporary transitions for these cases.

New APIs

Add newApi when the published API documentation does not contain the target. The component renders inline code until the target exists. It then renders a link and writes a cleanup warning.

<ApiLink package="fluid-framework" api="NewApi" newApi />

<PackageLink package="new-package" newApi />

Renamed APIs and packages

Use { previous, new } to support both sides of a rename. The component links to new when it exists and otherwise links to previous.

<ApiLink
	package="fluid-framework"
	api={{ previous: "OldApi", new: "(NewApi:class)" }}
/>

<PackageLink package={{ previous: "old-package", new: "new-package" }} />

When the new target becomes available, the build writes a warning. Replace the transition object with the new value:

<ApiLink package="fluid-framework" api="(NewApi:class)" />

<PackageLink package="new-package" />

Invalid and ambiguous API references remain build errors. Explicit child content is preserved in all transition states.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (633 lines, 5 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[Copilot]

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Joshua Smithrud (Josmithr)]

Note for reviewers: this is an example of one of the classes of problems this PR is aimed at addressing. We added docs for a new property that hadn't yet been released and initially tried to link to it, which caused the website build to fail. We can now "stage" the link, which will go live as soon as the API has been released.

[Wayne Ferrao (WayneFerrao)]

The core refactor is clean and the tests looks good. Just take a look at the missing md link

[github-actions]

Bundle size comparison

Base commit: could not be determined; will be reported when the comparison runs
Head commit: d72511653542681d546b39d561a6f06d793c99c7

Pending — Build - client packages is running. Results will appear here when the build completes.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --host 127.0.0.1 --no-open

[SUCCESS] Serving "build" directory at: http://127.0.0.1:3000/

> fluid-framework-website@0.0.0 check-links
> linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  340614 links
    2042 destination URLs
    2297 URLs ignored
       0 warnings
       0 errors