Redirection

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

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:

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