redirection

name	redirection
description	How to delete, rename, or move articles on Microsoft Learn while preserving Platform IDs, preventing broken links, and managing redirects.

Skill: Redirection on Microsoft Learn

Purpose

This skill describes how to properly redirect content when articles are deleted, renamed, or moved on Microsoft Learn. Proper redirection prevents broken links, avoids 404 errors, and ensures the Platform ID algorithm correctly associates the new location with the original content.

When Redirection Is Required

Redirection is always required for:

• Renaming files (not just article titles)
• Moving a file to a different folder or directory
• Migrating content to a new repository
• Merging files

These operations are treated as "remove and replace" by the platform, not as in-place updates.

The Redirection File

Redirects are managed in a JSON file at the repo root, typically named .openpublishing.redirection.json. Each entry maps an old source path to a new target URL.

Entry Format

{
  "redirections": [
    {
      "source_path_from_root": "/articles/ai-services/content-safety/concepts/custom-categories-rapid.md",
      "redirect_url": "/azure/ai-services/content-safety/concepts/custom-categories",
      "redirect_document_id": true
    }
  ]
}

Properties

Property	Required	Description
source_path_from_root	Yes	Absolute path to the old file in the repo. Must start with /.
redirect_url	Yes	Target URL — can be a relative path, a site-relative path on Microsoft Learn, or an external URL.
redirect_document_id	No	Set to true to transfer the document ID (and reporting data like page views and rankings) from the old article to the target. Defaults to false if omitted.

Platform ID

The Platform ID is a unique identifier for Learn documents, designed to replace the Document ID system. Unlike Document ID, the Platform ID is automatically generated based on content similarity and URL redirection relationships.

Best Practices for Platform ID Continuity

1. Don't change content during file operations. The Platform ID relies on a 90% content similarity threshold. If similarity drops below 90%, the platform treats the documents as distinct entities with different IDs. Rename or move first, then make content changes in a separate PR.

2. Eliminate duplicate content:

   • Same repo: Delete the original and set up redirection in the same PR.
   • Cross-repo migration: Publish in the target repo and create the redirect in a first PR, then delete the old document within 24 hours in a second PR. After 24 hours the Platform ID is finalized.

[!WARNING] Not following redirection policies risks losing historical BI data. The Platform ID is also used by recommendations and search services — changes to the ID can make content inaccessible or degrade search results.

Redirection Workflows

Deprecating Content (Keep Published, Remove from Search)

Add the ROBOTS: NOINDEX metadata as the last entry in the article's YAML frontmatter, then republish:

ROBOTS: NOINDEX

This tells search engines not to index the page while still allowing crawlers to follow links on it to other pages.

Deleting an Article

1. Ensure you're listed as author in the article's metadata (update if not).
2. Delete the article file.
3. Add a redirect entry in .openpublishing.redirection.json pointing to an appropriate replacement page.
4. Include both the deletion and the redirect in the same PR.

Renaming a File

1. Create a copy of the article with the new file name.
2. Delete the old file.
3. Add a redirect from the old path to the new path in the redirection file.
4. Update the TOC entry for the article.

Moving a File

Same process as renaming — create the file in the new location, delete the original, add the redirect, and update the TOC.

Updating Cross-References

Don't rely on redirects alone for internal links. After any file operation, scan for and update cross-references:

# Find all files linking to the old article
Get-ChildItem -Recurse -Include *.md |
    Select-String '<old-article-name>' |
    Group-Object Path |
    Select-Object Name

Update or remove these cross-links in the same or a follow-up PR.

Post-Merge Checklist

After your PR merges, complete these steps:

Step	Details
Test redirects in staging	Verify the old URL redirects to the correct target before signing off
Update FWLinks	Check the FWLink tool for any links pointing to the old article and update them
Manage inbound links	Identify high-traffic non-Microsoft inbound links (blogs, forums) and coordinate updates if possible
Remove search cache (rare)	Only if content must be removed urgently for legal or severe customer issues — use Bing and Google removal tools
Review old redirects	Periodically review and clean up redirect entries based on your org's retention policy
Check Platform ID Dashboard	Verify that file URL changes follow best practices

Relationship with TOC and Breadcrumbs

When you delete, rename, or move an article, you must also update the corresponding TOC entry to reflect the new file path. If the move changes the article's URL structure, verify that the breadcrumb tocHref mappings still apply correctly.

Reference

• Redirect articles
• Moving or refactoring files in a repository
• Platform ID Dashboard