xplat-docs-platform-block

name	xplat-docs-platform-block
description	Guidance for using PlatformBlock in xplat MDX after ApiLink moved to registry-based resolution. Use when platform-specific prose or API symbols differ.
user-invocable	true

PlatformBlock In Xplat Docs

Purpose

PlatformBlock is for platform-specific content, not for API URL mechanics.

Use it when:

• prose differs by platform;
• sample code differs by platform;
• the actual symbol or member name differs by platform;
• a platform needs a manual external link or plain text because the API does not exist.

Do not use it just to handle package, prefix, suffix, or URL differences. ApiLink and the generated registry should handle those.

Correct Use

<PlatformBlock for="Angular">
  <ApiLink type="IGridState" />
</PlatformBlock>

<PlatformBlock for="React,WebComponents,Blazor">
  <ApiLink type="GridState" />
</PlatformBlock>

ApiLink Rules

• Prefer clean links: <ApiLink type="Grid" />.
• Add member when linking to a member.
• Add pkg only when check-mdx-links reports an ambiguity.
• Do not add exclude, excludePrefixFor, or excludeSuffixFor.
• Avoid new prefixed={false} or suffix={false} usage.

Formatting

Keep PlatformBlocks readable:

Some prose before.

<PlatformBlock for="Angular">
  Angular-only content.
</PlatformBlock>

<PlatformBlock for="React,WebComponents,Blazor">
  Shared xplat content.
</PlatformBlock>

Some prose after.

Avoid single-line PlatformBlocks unless they are already inside a compact inline context that cannot be safely restructured.