xplat-docs-api-map-sync - SKILL.md Agent Skill

name: xplat-docs-api-map-sync description: "Reference guide for syncing xplat ApiLink coverage from the legacy igniteui-xplat-docs apiMap data while keeping ApiLink markup registry-first. Use when importing missing links from igniteui-xplat-docs or auditing ApiLink coverage after API registry updates." user-invocable: true

Syncing Xplat ApiLink Coverage

Current Direction

The docs now resolve ApiLinks through the generated api-docs registry stored in src/data/api-link-index/{platform}/{staging-latest|prod-latest}.json.

The legacy igniteui-xplat-docs/apiMap files are useful for discovering missed references in old markdown, but they are not the final URL source of truth.

Rules

Prefer clean links: <ApiLink type="Grid" /> and <ApiLink type="Grid" member="rowSelection" />.
Use pkg only when the registry reports an ambiguous symbol name.
Use kind only when it is needed for Sass links or to disambiguate a real TypeDoc symbol.
Do not add exclude, excludePrefixFor, or excludeSuffixFor; those props are obsolete.
Avoid prefixed={false} and suffix={false} in new MDX. The registry should resolve the real symbol name.
Use PlatformBlock only when the prose or the actual symbol/member name differs by platform.
Never replace an existing ApiLink with backtick text only because one platform is missing it; report the miss and let the registry/API data decide.

Workflow

Use the local sibling repo ../igniteui-xplat-docs to inspect old apiMap or markdown references.
Add missing xplat ApiLinks to docs/xplat/src/content.
Run the registry checker:

npm run check-mdx-links:broken:angular
npm run check-mdx-links:broken:react
npm run check-mdx-links:broken:wc
npm run check-mdx-links:broken:blazor

For ambiguous results, add pkg or kind only where the report proves it is needed.
For member-missing results, first verify whether the member exists under a different name in the generated registry before changing MDX.
Keep generated reports under reports/ when they are useful for review.

Migration Helpers

docs/xplat/scripts/resolve-api-links.mjs can still be used to convert legacy backtick references into ApiLinks, but it must not emit prefix/suffix/exclude override props. Registry validation is the follow-up authority.

docs/xplat/scripts/fix-api-link-attrs.mjs may strip CLR generic arity and add kind="interface" for known apiMap/TypeDoc mismatches. It must not add prefixed={false} or suffix={false}.