feat(): add relative link validation and update cross-topic references

.github/CONTRIBUTING.md

@@ -446,6 +446,16 @@ The xplat documentation uses a single MDX source file shared across all four pla
 
 When creating a shared topic that covers multiple grid types (e.g. Grid, TreeGrid, HierarchicalGrid), use the `{ComponentName}` token in prose and code examples so the same file can be referenced from each grid's navigation entry with a different `{ComponentName}` value injected. Each generated output file gets its own resolved content without duplicating the MDX source.
 
+### Grid template files (`_shared/`)
+
+Files under `docs/xplat/src/content/*/components/grids/_shared/` are template sources expanded by `docs/xplat/scripts/generate.mjs` into per-grid-type output under `docs/xplat/generated/`. They are **excluded** from the direct relative-link check; their links are validated via the generated output after the generate step runs.
+
+Cross-references from a `_shared/` file to grid-specific topics must use relative paths that resolve from the **generated** location, e.g. `../grid/groupby.mdx` (not `./groupby.mdx`, which would resolve from the `_shared/` directory itself).
+
+### Relative link convention
+
+All cross-page links must carry the `.mdx` extension. Both explicit (`./page.mdx`, `../dir/page.mdx`) and bare (`page.mdx`) forms are accepted by the checker and by the `remarkMdLinks` build plugin. Run `npm run check-relative-links:ci` to validate all links after making changes.
+
 # <a name='#updating-of-data-visualization-related-topics'>Updating of Data Visualization related topics</a>
 
 The cross-platform (xplat) documentation MDX source files live in this repository under `docs/xplat/src/content/`. Edit them directly here. The generated per-platform output is produced by the build scripts under `docs/xplat/scripts/`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@ Closes #
 
  - [ ] check topic's TOC/menu and paragraph headings
  - [ ] Include TOC topic labels in the topic content when it has a valuable update, is new, or is considered `preview` / `beta`
- - [ ] link to other topics using `../relative/path.md`
+ - [ ] link to other topics using `./page.mdx` or `../relative/path.mdx` (`.mdx` extension required)
  - [ ] at the References section at the end of the topic add links to topics, samples, etc
  - [ ] reference API documentation instead of adding a section with API
 

.github/workflows/lint.yml

@@ -89,3 +89,59 @@ jobs:
             echo "$RESULT" >> "$GITHUB_STEP_SUMMARY"
             echo '```' >> "$GITHUB_STEP_SUMMARY"
           fi
+
+  check-relative-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - run: npm ci
+
+      # Sync xplat-generated Angular content into docs/angular/src/content
+      # before scanning so the angular tree is complete (same as the angular build).
+      - name: Sync xplat → angular (en)
+        run: npm run sync:generated-from-xplat --prefix docs/angular
+
+      - name: Sync xplat → angular (jp)
+        run: npm run sync:generated-from-xplat:jp --prefix docs/angular
+
+      - name: Generate angular content (en)
+        run: npm run generate:en --prefix docs/angular
+
+      - name: Generate angular content (jp)
+        run: npm run generate:jp --prefix docs/angular
+
+      # Expand xplat _shared/ templates into docs/xplat/generated/ for all
+      # non-Angular platforms so the generated grid pages are present when
+      # the xplat link check runs (Angular is already generated by the sync step).
+      - name: Generate xplat content (en)
+        run: |
+          npm run generate:react --prefix docs/xplat
+          npm run generate:webcomponents --prefix docs/xplat
+          npm run generate:blazor --prefix docs/xplat
+
+      - name: Generate xplat content (jp)
+        run: |
+          npm run generate:react:jp --prefix docs/xplat
+          npm run generate:webcomponents:jp --prefix docs/xplat
+          npm run generate:blazor:jp --prefix docs/xplat
+
+      - name: Check relative links
+        shell: bash
+        run: |
+          set -o pipefail
+
+          EXIT=0
+          echo '## Relative Link Check' >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+          node scripts/check-relative-links.mjs --platform=xplat 2>&1 | tee -a "$GITHUB_STEP_SUMMARY" || EXIT=1
+          node scripts/check-relative-links.mjs --platform=angular 2>&1 | tee -a "$GITHUB_STEP_SUMMARY" || EXIT=1
+
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          exit $EXIT

README.md

@@ -66,6 +66,71 @@ The MDX files currently use these documentation components from `igniteui-astro-
 | `PlatformBlock` | Shows content only for selected platforms. |
 | `Sample` | Embeds runnable or linked product samples. |
 
+## Checking Relative Links
+
+Use the root `check-relative-links` scripts to validate that every relative cross-page link in the MDX source resolves to an existing file.
+
+### Link convention
+
+All relative cross-page links must carry the `.mdx` extension. Preferred forms:
+
+- `./page.mdx` — same-directory link (explicit relative)
+- `../folder/page.mdx` — parent-directory link (explicit relative)
+- `page.mdx` — bare same-directory link (also accepted by the checker)
+
+The `.mdx` extension enables editor Go-to-Definition (Ctrl+Click). The `remarkMdLinks` plugin strips the extension and makes the URL absolute at build time. The link checker validates that the target file exists and normalizes bare `page.mdx` links as same-directory relative.
+
+### Angular content pipeline
+
+The Angular documentation is assembled from three sources before being checked:
+
+1. **xplat sync** — `docs/xplat/src/content/` is generated into platform-specific output and then copied into `docs/angular/src/content/` by the sync scripts.
+2. **Grid generation** — `docs/angular/src/content/en/grids_templates/` and `jp/grids_templates/` are template files shared across all four grid types (Grid, TreeGrid, HierarchicalGrid, PivotGrid). `generate.mjs` expands them into the individual component pages under `docs/angular/src/content/en/components/grid/`, `treegrid/`, `hierarchicalgrid/`, and `pivotGrid/`. These template directories are excluded from link checking (same as xplat `_shared/`).
+3. **Link check** — the checker scans the fully assembled `docs/angular/src/content/` tree.
+
+The check must run **after** both steps above, otherwise it scans stale or incomplete files and misses links that only exist in generated output.
+
+> **xplat:** The checker scans only `docs/xplat/src/content/` (source files). The `docs/xplat/generated/` tree is excluded — `_shared/` links are validated via the source, and generated output correctness is owned by the generate scripts.
+
+### Commands
+
+The preferred command to replicate the exact CI pipeline locally:
+
+```bash
+npm run check-relative-links:ci
+```
+
+This runs the full chain in order:
+1. Sync xplat → angular (en)
+2. Sync xplat → angular (jp)
+3. Generate angular grid pages (en)
+4. Generate angular grid pages (jp)
+5. Generate xplat React + WC + Blazor pages (en) — expands `_shared/` templates and rewrites `_shared/` paths in output
+6. Generate xplat React + WC + Blazor pages (jp)
+7. Check xplat links (source `docs/xplat/src/content/` + `docs/xplat/generated/`)
+8. Check angular links
+
+> **Note:** The generate scripts rewrite `../_shared/X.mdx` → `./X.mdx` (and `./_shared/X.mdx` → `./grid/X.mdx`) in the generated output so links in the expanded files resolve correctly.
+
+Other available commands:
+
+| Scope | Command |
+|---|---|
+| Full CI simulation (preferred) | `npm run check-relative-links:ci` |
+| Angular only (runs generate first) | `npm run check-relative-links:angular` |
+| xplat (generates all platforms, then checks source + generated) | `npm run check-relative-links:xplat` |
+| Both trees, no setup (skips generate steps) | `npm run check-relative-links` |
+| Angular report to file | `npm run check-relative-links:report:angular` |
+| xplat report to file | `npm run check-relative-links:report:xplat` |
+
+The checker exits with code 1 on any broken link and prints each failure with a reason code:
+
+| Reason | Meaning |
+|---|---|
+| `[not found]` | Target file does not exist |
+| `[add .mdx extension]` | Link is `./page` — has `./` prefix but is missing the `.mdx` extension |
+| `[use ./page.mdx instead]` | Link is `(page)` — bare path with no extension and no `./` prefix |
+
 ## Checking MDX API Links
 
 Use the root `check-mdx-links` scripts to validate `ApiLink` references:
@@ -94,7 +159,6 @@ Fix ambiguous links by adding a specific `pkg` or `kind` prop. If the correct ta
 
 - [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md): day-to-day editing, generated-content behavior, and report expectations.
 - [API-LINK-WORKFLOW.md](API-LINK-WORKFLOW.md): API registry flow, `ApiLink` resolution, ambiguity handling, and checker commands.
-- [migration.md](migration.md): MDX migration rules and component examples.
 
 ## Contributing