Repository navigation
Open
Description
Task type
- Other: contributor docs and tooling disagree
Description
The contributor docs and skills say every xplat topic must declare platformType, that it has no default, and that a page without it does not build. The generator does the opposite: a missing platformType is read as web-only, and the build passes.
What the code does
platformType()indocs/xplat/scripts/lib/api-terms.mjsreturns'web-only'when the field is missing. Its comment says this is temporary:Temporarily, a page that does not state it is web-only. The web-only pages carry no platformType while the JSON snippets work merges, so they stay identical to the web documentation and their owners have no edits from it to review. Restore the error below once that has landed.
docs/xplat/scripts/check-doc-scope.mjs(line 82) applies the same default, so thesnippet-checksworkflow reports 0 errors for these pages.
The JSON snippets work landed in #497 on 2026-10-20, but the error was never restored.
What the docs say (all on vnext)
AGENTS.md:74.agents/README.md:46docs/xplat/API-TERMS.md:17.github/skills/xplat-docs-api-links/SKILL.md:16: "a missing or unknown value stops the build".github/skills/xplat-docs-json-snippets/SKILL.md:13and:127: "a page without it does not build".agents/skills/igniteui-doc-topics/references/house-style.md:64and:68,create-workflow.md:28, andaudit-rubric.md:135, which rates a missingplatformTypeas a D0 blocker
Scale
en: 160 of the 319 pages underdocs/xplat/src/content/en/componentshave noplatformType; 42 of them aregrids/_shared/templates. Only 2 pages declareweb-onlyexplicitly, so almost every web-only page relies on the default.jp: 160 of 302.
Why it matters
- New topics can leave out
platformTypeand pass CI. The rewritten combo topics in feat(combo-templates): update combo templates topics #1040 are a current example. - The audit rubric rates a missing value as a blocker on pages CI accepts, and agents following the skills report build failures that don't happen.
Options
- Finish what the code comment describes. Add
platformTypeto the pages that lack it (web-onlyfor almost all), then restore the error inplatformType()and makecheck-doc-scope.mjsreport a missing value. The JP pages are synced by the gh-aw workflows, so decide whether they get the field in the same change or through the sync. - Keep the default. Update the docs listed above to say a missing
platformTypemeansweb-only, and drop "Temporarily" from the two code comments.
Acceptance criteria
- The docs and the code agree on what a missing
platformTypedoes. - With option 1: every page under
docs/xplat/src/content/{en,jp}/componentsdeclaresplatformType, and a page without it failsgenerateand thecheck-doc-scope.mjsstep insnippet-checks. - With option 2: none of the files listed above says the field is required or that the build stops without it.
Related resources
- Xplat docs xplat json snippet support and refactor and automated docs testing #497: the JSON snippets work the default was waiting on
docs/xplat/scripts/lib/api-terms.mjs:platformType()docs/xplat/scripts/check-doc-scope.mjs.github/workflows/snippet-checks.yml: runscheck-doc-scope.mjsforenandjp
Metadata
Metadata
Assignees
Labels
No labels
Activity