xplat-docs-api-map-sync

name	xplat-docs-api-map-sync
description	Reference guide for synchronizing the xplat docs ApiLink references with the upstream igniteui-xplat-docs apiMap data. Covers running scripts/resolve-api-links.mjs to inject ApiLink tags from `IgxFoo.bar`-style backtick references in MDX, syncing docConfig.json with the sibling igniteui-xplat-docs repo, generating per-platform broken-link reports via scripts/check-api-links.mjs, and applying exclude= props to broken ApiLink tags via scripts/apply-excludes.mjs. Use when bumping API package versions, after merging vNext content, or when ApiLink coverage drifts from upstream.
user-invocable	true

AI Agent Guide — Syncing xplat-docs ApiLink Coverage

Context

This Astro xplat docs project mirrors the legacy gulp-based igniteui-xplat-docs pipeline. The legacy pipeline used apiMap JSON files (one per platform) and docConfig.json to:

1. Convert backtick-prefixed type/member references (`IgxGrid.sort`) into resolved API URLs.
2. Resolve the right per-platform package version, prefix, suffix, and base URL.

Here those responsibilities are split across:

Responsibility	Implementation
apiMap lookup of valid types / members	Per-platform JSON files in sibling igniteui-xplat-docs/apiMap/{Angular,React,Blazor,WebComponents}/*.apiMap.json
docConfig (package versions, prefixes, base URLs)	docs/xplat/docConfig.json
Backtick → <ApiLink/> conversion	docs/xplat/scripts/resolve-api-links.mjs (or workspace-level equivalent)
Verifying generated URLs against staging	scripts/check-api-links.mjs
Auto-applying exclude= for broken URLs	scripts/apply-excludes.mjs
Migrating <PlatformBlock for="..."><ApiLink/></PlatformBlock> to exclude=	scripts/migrate-platformblock-to-exclude.mjs

---

Sibling Repository Layout

The igniteui-xplat-docs repo is at https://github.com/IgniteUI/igniteui-xplat-docs.

igniteui-xplat-docs/
  apiMap/
    Angular/*.apiMap.json
    React/*.apiMap.json
    Blazor/*.apiMap.json
    WebComponents/*.apiMap.json
  docConfig.json
  gulpfile.js              ← legacy reference; do not run

The astro-components repo is also a sibling (checked out next to docs-template) and is symlinked into node_modules/igniteui-astro-components via the workspace config in docs-template/package.json. The <ApiLink/> Astro component lives there at src/components/mdx/ApiLink/ApiLink.astro.

---

Workflow 0 — Applying Fixes from an Existing mdx-link-report

When mdx-link-report-{angular,react,wc,blazor}.md files already exist at the repo root (generated by a previous check-mdx-links run), apply all suggested fixes in one step:

# Preview what will change (no writes)
node scripts/apply-mdx-report-fixes.mjs --dry-run

# Apply all fixes across all four platform reports
node scripts/apply-mdx-report-fixes.mjs

The script reads every mdx-link-report-*.md it finds, parses each broken-URL entry's FIX line, and merges the appropriate prop (excludeSuffixFor, excludePrefixFor, or exclude) onto the matching <ApiLink> tag in the xplat source file. Angular report paths are automatically remapped to their canonical docs/xplat/src/content/ source (except grids/ and changelog/ which Angular owns directly).

After applying, re-run the check to confirm the broken count drops to 0:

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

---

Workflow 1 — After Bumping a Platform Version

When a platform's API package version changes (e.g. Angular 21.1 → 21.2) some symbols may be renamed, removed, or relocated. Walk through:

# 1. Sync docConfig.json with upstream (manual diff)
# Compare docs/xplat/docConfig.json with sibling igniteui-xplat-docs/docConfig.json.
# Apply any version, base-URL, or package-key changes; preserve local-only fields
# (e.g. codeSandboxButtonInject).

# 2. Generate per-platform broken-link reports against staging
node scripts/check-api-links.mjs --platform=angular
node scripts/check-api-links.mjs --platform=react
node scripts/check-api-links.mjs --platform=wc
node scripts/check-api-links.mjs --platform=blazor
# → produces api-link-report-{angular,react,wc,blazor}.md at repo root.

# 3. Auto-apply exclude= to ApiLink tags whose URLs are broken
node scripts/apply-excludes.mjs --dry-run    # preview
node scripts/apply-excludes.mjs              # apply

# 4. Re-run reports — broken count should now be near 0
node scripts/check-api-links.mjs --platform=angular
# (and the other three)

Workflow 2 — After Importing New Content from vNext

Critical rule: never demote an existing <ApiLink/> to backtick text. If a URL is broken on some platforms, add exclude="Platform" — never remove the link. Backtick text is only acceptable when the type has no TypeDoc page on any platform and was never an ApiLink in the upstream content.

Correct pipeline order — must run in this sequence:

# 1. Strip Igr/Igx/Igc/Igb prefixes from backtick-wrapped prose refs.
#    (Xplat content is platform-agnostic. `IgrToolbar` → `Toolbar`)
#    Script skips code fences, JSX tags, and PlatformBlock-wrapped content
#    (e.g. <PlatformBlock for="React">`IgrFoo`</PlatformBlock> is intentional).
node scripts/fix-igr-backtick-prefix.mjs

# 2. Convert bare backtick refs (`Toolbar`, `DataChart`, etc.) into <ApiLink/>
#    using the sibling igniteui-xplat-docs/apiMap JSON files.
#    Reads mentionedTypes: frontmatter to scope the lookup per file.
cd docs/xplat && node scripts/resolve-api-links.mjs

# 3. Fix <ApiLink> attributes: strip CLR arity suffixes, add prefixed={false}
#    for enums, reclassify class → interface for known mis-classified types.
#    Does NOT demote ApiLinks to backtick text.
node scripts/fix-api-link-attrs.mjs

# 4. Migrate any <PlatformBlock for="..."><ApiLink/></PlatformBlock> wrappers
#    that exist purely for platform-omission into exclude= props.
cd /c/Repos/docs/docs-template && node scripts/migrate-platformblock-to-exclude.mjs

# 5. Run Workflow 1 (steps 2-4) to verify and auto-fix broken URLs.

Angular content syncs automatically — after fixing xplat, run:

cd docs/xplat && node scripts/generate.mjs --platform=Angular --lang=en
cd /c/Repos/docs/docs-template && node docs/angular/scripts/sync-generated.mjs --lang=en
# repeat for --lang=jp, --lang=kr if needed

---

Script Reference

scripts/check-api-links.mjs

Walks docs/xplat/src/content/**/*.mdx, extracts every <ApiLink/> tag, computes the staging URL per platform, and HEAD-checks each URL.

• Honors enclosing <PlatformBlock for="..."> (stack-based intersection) so a tag wrapped for one platform is checked only on that platform.
• Honors exclude="..." on the tag itself — listed platforms are dropped from the check set.
• Output:
  • Console summary (OK / Not found / HTTP / Total broken).
  • api-link-report-<platform>.md with details on every broken URL and the MDX files it appears in.

CLI:

node scripts/check-api-links.mjs --platform=angular|react|wc|blazor

scripts/apply-excludes.mjs

Reads all four api-link-report-*.md files, builds a per-file map of broken URLs → platforms, then walks each file's <ApiLink/> tags and merges exclude="..." for any matching tag. Idempotent.

Matching algorithm:

• Strip platform prefix (Igr/Igx/Igc/Igb) from URL type names.
• Generate two key variants per URL — with and without Component/Module/Directive/Element suffix — to match Angular tags written either with or without the suffix.
• Lowercase member fragments so Blazor's PascalCased #Condition matches a tag's member="condition".
• On tag side, key is (stripPrefix(type) | lowercased member | kind || 'class').

CLI:

node scripts/apply-excludes.mjs --dry-run
node scripts/apply-excludes.mjs

scripts/migrate-platformblock-to-exclude.mjs

Finds the anti-pattern:

<PlatformBlock for="A,B,C">
<ApiLink ... />
</PlatformBlock>

When for= lists exactly N-1 of the 4 platforms, rewrites to:

<ApiLink ... exclude="MissingPlatform" />

Skips tags that already have an exclude= attribute.

scripts/resolve-api-links.mjs (or workspace equivalent)

Walks MDX content and converts backtick-only API references like `IgxGrid.sort` into <ApiLink/> tags by looking up the type and member in the sibling igniteui-xplat-docs/apiMap/*.json files.

---

docConfig.json Sync Checklist

When syncing docs/xplat/docConfig.json with the upstream igniteui-xplat-docs/docConfig.json:

• Pull in any new platform version numbers (apiPackages[platform][packageId].version).
• Pull in any new packageId entries (e.g. new component packages added upstream).
• Preserve local-only fields the Astro project uses but the legacy pipeline does not — e.g. codeSandboxButtonInject.
• Leave prefix, classSuffix, and apiUrl alone unless explicitly changed upstream — only Angular has a non-empty classSuffix ("Component") for chart/gauge/map/excel/spreadsheet packages.

---

Common Pitfalls

Pitfall	Symptom	Fix
Forgot to re-run check-api-links after apply-excludes	Same broken count reported	Re-run check after apply; report is regenerated.
Member casing mismatch (Blazor PascalCase vs MDX lowercase)	Blazor 0 tags updated even though report shows breaks	apply-excludes.mjs already handles this via lowercase key. If you customize, preserve the lowercase logic.
Angular Component suffix only on certain packages	Some Angular URLs still broken after apply	Verify apply-excludes.mjs baseVariants() adds both with-suffix and without-suffix variants.
replace_string_in_file silently failing on apply-excludes.mjs	Edits report success but file unchanged	Use a Node-based file patcher: readFileSync + .replace() + writeFileSync. Always grep to verify.
Running resolve-api-links BEFORE fix-igr-backtick-prefix	Backtick refs with Igr prefix can't be resolved; new backtick Toolbar refs created after fix-igr go unconverted	Always run fix-igr first, then resolve-api-links, then fix-api-link-attrs.
Adding types to a NONEXISTENT_TYPES demotion list in fix-api-link-attrs	ApiLinks removed from content; replaced with IgrFoo backtick text	Never demote ApiLinks. fix-api-link-attrs.mjs has NO demotion logic. Handle broken URLs with exclude= via apply-excludes.mjs.
fix-igr-backtick-prefix stripping Igr prefix inside PlatformBlock	<PlatformBlock for="React">IgrFoo</PlatformBlock> → Foo (wrong)	The script already skips lines containing <PlatformBlock. Do not remove that guard.

---

Related Skills

• xplat-docs-api-links — ApiLink prop reference
• xplat-docs-platform-block — PlatformBlock and ApiLink exclude= semantics