Fix broken links failing Verify Site CI on PRs #9736 and #9667 #9747
Description
Summary
The "Verify Site" CI check is failing on PRs #9736 and #9667 due to broken links on the generated site. All of these broken links are pre-existing on main — neither PR introduced them. They block CI for any PR that triggers a full site build.
This issue consolidates all broken links found across both CI runs with proposed fixes for each.
Broken Links and Proposed Fixes
1. Azure.Identity release link — wrong ref prefix (release/ branch vs tag)
Broken URL:
https://github.com/Azure/azure-sdk-for-net/blob/release/Azure.Identity_1.18.0/sdk/core/Azure.Core/src/docs/ConfigurationAndDependencyInjection.md
Appears on: releases/2026-03/dotnet.html
Root cause: The URL uses blob/release/Azure.Identity_1.18.0 (a branch name that doesn't exist). The tag Azure.Identity_1.18.0 exists but has no release/ prefix.
Fix: Change release/Azure.Identity_1.18.0 to Azure.Identity_1.18.0 in the source YAML that generates this link.
Correct URL: https://github.com/Azure/azure-sdk-for-net/blob/Azure.Identity_1.18.0/sdk/core/Azure.Core/src/docs/ConfigurationAndDependencyInjection.md
2. Azure.AI.VoiceLive — wrong SDK subdirectory (sdk/ai/ vs sdk/voicelive/)
Broken URLs:
https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/ai/Azure.AI.VoiceLive/
https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/ai/Azure.AI.VoiceLive/CHANGELOG.md
Appears on: releases/latest/dotnet.html, releases/latest/all/dotnet.html, releases/latest/, releases/2025-10/dotnet.html, index.html
Root cause: The package lives at sdk/voicelive/Azure.AI.VoiceLive/, not sdk/ai/Azure.AI.VoiceLive/. The RepoPath in dotnet-packages.csv likely has the wrong directory.
Fix: Update RepoPath in _data/releases/latest/dotnet-packages.csv from sdk/ai/Azure.AI.VoiceLive/ to sdk/voicelive/Azure.AI.VoiceLive/.
Correct URLs:
https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/voicelive/Azure.AI.VoiceLive/https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/voicelive/Azure.AI.VoiceLive/CHANGELOG.md
3. Packages.Data.props — file removed from azure-sdk-for-net
Broken URL:
https://github.com/Azure/azure-sdk-for-net/blob/main/eng/Packages.Data.props
Appears on: dotnet_introduction.html
Root cause: eng/Packages.Data.props was deleted from the azure-sdk-for-net repo. No direct replacement file exists at eng/.
Fix: Remove or replace the reference in the source markdown for dotnet_introduction.html. If the content it referenced (package listing data) is available elsewhere, link to that. Otherwise, remove the link entirely.
4. StorSimple MSDocs links — deprecated package docs removed (2 URLs)
Broken URLs:
https://learn.microsoft.com/javascript/api/overview/azure/arm-storsimple1200series-readme
https://learn.microsoft.com/javascript/api/overview/azure/arm-storsimple8000series-readme
Appears on: releases/deprecated/js.html, releases/deprecated/index.html
Root cause: Microsoft removed the API docs for these deprecated StorSimple JS packages. The MSDocs column in js-packages.csv may be empty (triggering auto-generation) or may contain these dead URLs.
Fix: Set MSDocs="NA" for @azure/arm-storsimple1200series and @azure/arm-storsimple8000series in _data/releases/latest/js-packages.csv. The "NA" value tells the template to skip MSDocs link generation (falls through to GHDocs). Note: the automated Update-Release-Versions.ps1 pipeline may have already fixed this — verify the current CSV values before making changes.
5. Neon.Postgres (liftrneon) spec links — spec removed from azure-rest-api-specs (5 unique URLs)
Broken URLs:
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/stable/2025-03-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2025-03-01-preview
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2024-12-22-preview
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2024-08-01-preview
Appears on: releases/latest/all/specs.html, releases/latest/mgmt/specs.html
Root cause: The specification/liftrneon/ directory was entirely removed from the main branch of Azure/azure-rest-api-specs. The migration PR (azure-rest-api-specs#38484) was closed without merging. The spec no longer exists on main.
Fix: Remove the liftrneon entries from _data/releases/latest/specs.csv, or update their SpecPath to point to wherever the Neon.Postgres spec now lives. If the spec has been fully removed, delete these rows from specs.csv.
6. Compute spec links — old RP subdirectory names (4 unique URLs)
Broken URLs:
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-11-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/DiskRP/stable/2024-03-02
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/GalleryRP/stable/2024-03-03
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/RecommenderRP
Appears on: releases/latest/mgmt/specs.html
Root cause: The azure-rest-api-specs repo restructured the Compute spec directories. The old names (ComputeRP, DiskRP, GalleryRP, RecommenderRP) were replaced with new names (Compute, Compute, Compute, Recommender). DiskRP and GalleryRP API versions are now consolidated under the Compute directory.
Fix: These broken links appear to be generated by the spec page template rather than stored literally in specs.csv (which already uses correct paths). Investigate the template logic in _includes/ that constructs spec GitHub URLs. If the URLs are derived from other CSV columns or computed differently than the SpecPath column, update accordingly.
| Old (broken) path | Correct path |
|---|---|
Microsoft.Compute/ComputeRP/stable/2024-11-01 |
Microsoft.Compute/Compute/stable/2024-11-01 |
Microsoft.Compute/DiskRP/stable/2024-03-02 |
Microsoft.Compute/Compute/stable/2024-03-02 |
Microsoft.Compute/GalleryRP/stable/2024-03-03 |
Microsoft.Compute/Compute/stable/2024-03-03 |
Microsoft.Compute/RecommenderRP |
Microsoft.Compute/Recommender |
7. KeyVault spec links — missing nested subdirectory (2 unique URLs)
Broken URLs:
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/keyvault/resource-manager/Microsoft.KeyVault/stable/2025-05-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/keyvault/resource-manager/Microsoft.KeyVault/preview/2026-03-01-preview
Appears on: releases/latest/mgmt/specs.html
Root cause: Same TypeSpec restructuring issue. The KeyVault spec moved from Microsoft.KeyVault/stable/ to Microsoft.KeyVault/KeyVault/stable/. The specs.csv already has the correct paths, so this is a template generation issue.
| Old (broken) path | Correct path |
|---|---|
Microsoft.KeyVault/stable/2025-05-01 |
Microsoft.KeyVault/KeyVault/stable/2025-05-01 |
Microsoft.KeyVault/preview/2026-03-01-preview |
Microsoft.KeyVault/KeyVault/preview/2026-03-01-preview |
8. Marketplace Catalog spec links — wrong namespace (2 unique URLs)
Broken URLs:
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/marketplacecatalog/resource-manager/Microsoft.Products/Products
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/marketplacecatalog/resource-manager/Microsoft.Reviews/Reviews/preview/2023-01-01-preview
Appears on: releases/latest/mgmt/specs.html
Root cause: The specs use namespace Microsoft.Marketplace but the generated links use Microsoft.Products and Microsoft.Reviews. Same template generation issue.
| Old (broken) path | Correct path |
|---|---|
Microsoft.Products/Products |
Microsoft.Marketplace/Products |
Microsoft.Reviews/Reviews/preview/2023-01-01-preview |
Microsoft.Marketplace/Reviews/preview/2023-01-01-preview |
Notes
- All broken links are pre-existing on
main— they affect any PR that triggers a full site build. - For spec links (categories 5-8), the
specs.csvdata appears correct, but the generated URLs are wrong. The spec page template logic should be investigated to determine how it constructs GitHub URLs from the CSV data. - The correct approach for each broken link is to find and use the valid URL. Only use "NA" when no valid URL exists (e.g., deleted docs, removed specs).
- References: Add new release folder structure #9736, cpp release notes for the 2026-03 release #9667