Redirection options

1. Moving from MTPS to OPS

Scenario: When you move from MTPS to OPS.

See MTPS redirection

2. Topic level redirection in OPS

Scenario: A file or subset of files are renamed.

Open Publishing supports redirection at the topic level. You need to keep the former file (File A) in your repo and create a new file with the new name (File B). In case you would like to eventually remove the original file (File A), please refer to master redirection file.

Write a metadata with name "redirect_url" in the yaml header, then the page will redirect to the topic or page specified. Note that the target URL needs to be either a absolute URL/path or the path relative to the site root.


  1. A full/absolute URL



  2. A partial URL without the domain, which implies that the target URL is within the same domain as the source URL, pointing to a published folder from OPS (windowscontainers is the folder). In this case, the index page under the specified folder would be used as redirection target.

    redirect_url: /virtualization/windowscontainers/


    redirect_url: /azure/virtual-machines/windows/
  3. A partial URL without the domain, that points to a folder and file name that's published with OPS. Leave off the file name extension (e.g. .md). In these examples, getting-started and virtual-machines-windows-hero-tutorial are the file names.

    redirect_url: /virtualization/windowscontainers/getting-started


    redirect_url: /azure/virtual-machines/windows/virtual-machines-windows-hero-tutorial

When a OPS page is redirected to another OPS page, OPS provides a mechanism to allow carrying over "ms.documentid" to the target OPS page by meta "redirect_document_id". This could be used when user wants to transfer the data collected from the source page to the target one. For example, the redirected-out page can be specified as following:

redirect_url: /virtualization/windowscontainers/ 
redirect_document_id: TRUE 


redirect_url:  /azure/virtual-machines/windows/
redirect_document_id: TRUE 


Mapping a redirect_document_ID across docsets is NOT supported at this time.

3. Master Redirection File

In majority of the cases, user would like to remove the source file once the redirection is activated. We provide the users a way to maintain those redirections in a centralized file without the need of keeping the obsoleted files.

The master redirection file is a JSON file located and consists of a list of redirection pairs.

  • File name: .openpublishing.redirection.json
  • File path: at the repository root
Value Explanation Required or Optional
source_path The relative file path to the repository root (with file extension). Remember the master redirection file is located at the root of the repo, so you need to include the docset name as part of the path to the file. Required
redirect_url Target URL to redirect to. It can be either an absolute url or a url relative to the root of the same site where the source was published to. Thus, you need to start with "/" and add the base URL path followed by the rest of the target URL Required
redirect_document_id Indicates whether you would like to keep the document_id or not from the previous file. It is a boolean. If omitted, value is set to false. Required


The files referenced as source in the master redirection file should not exist in the Git repository. So if a redirection needs to be managed in the master redirection file, the original file must be removed. If not removed, you will receive a [Warning] '' would be overwritten by redirection rule configured in master redirection file .openpublishing.redirection.json. Please remove the original file to resolve this warning. in your build output.


  "redirections": [ 
        "source_path": "abc/", 
        "redirect_url": "/abc/xyz", 
        "redirect_document_id": true 
        "source_path": "abc/",
        "redirect_url": "", 
        "redirect_document_id": false 

We also build some validations around the redirection rules, which includes

Rules Error or Warning Examples
[within repo] source_path should not be null or empty; otherwise result the following error. (source_path for redirect_url 'xxx' is null or empty.) Error "source_path": null
[within repo] source_path should not be above repository root path; otherwise result the following error. (source_path '' is above the root path 'yyy'.) Error "source_path": /a/
[within repo] redirect_url should not be null or empty; otherwise result the following error. (redirect_url for source_path 'xxx' is null or empty.) Error "redirect_url": null
[within repo] redirect_url should not be relative path; otherwise result error Error "redirect_url": c/d
[within repo] There should not be duplicated entries in mapping files; otherwise result the following error. (There are duplicated entries for source_path '' in redirection mapping file.) Error
[within repo] If the redirection file still exists, result the following warning. ( would be overwritten by redirection rule configured in master redirection file .openpublishing.redirection.json. Please remove the original file to resolve this warning) Warning
[within docset, and all redirect_document_id = true] Multiple topics redirect to same page, pick up first redirect-from page (in order of relative path in docset) to generate document id Warning,, all redirect to set document id of to
[within docset, and all redirect_document_id = true] Recursive redirection Error -> -> or ->
[within docset] not supported yet multi-hoop redirection Warning -> ->

The redirection rule is not locale specific, one rule configured in English repository would be automatically applied to all other locales. The only thing needs to be pointed out here is, after the redirection, OPS would select the user's default locale to display the redirection target documentation. The user's default locale is determined by cookie (which is set by locale picker) and then browser language setting.

4. DocSet and Folder Level Redirection

Those levels of redirection would be managed on Network Layer (Akamai or similiar) to obtain the best performance. Please follow the steps described in below section to set up those redirection rules once needed.

5. Site Level Redirection


Applies to:, MSDN, TN, and content published with OPS.


  • For Docs, When both the endpoints have to be in place to stop bad end-user experience until the traffic to older endpoints reduces to get the redirection rule removed from Akamai.
  • For MSDN/TN and we do not do redirection from Akamai, but can write a ARR rule for the same depending on the request.


  1. Updates on the base URL in OPS
  2. Folder renaming in the Git repo other than the docset folder

Please open the request 5 business days in advance.


  1. Open a request in SiteHelp portal.
  2. Tag the request with Redirection tag.
  3. Include the following information:
    • Current and New URLs
    • Date and time when the redirection needs to take place:

Ticket example

Reason: We are rebranding our product. As a result, we need docset renaming and site-level redirection.
Current URL: 
Target URL:
Date and time to go live: October 16, 5pm

What you can expect after the ticket is opened:

  • APEX Engineering will contact you to acknowledge your request and follow up on any questions.
  • APEX Engineering will ask you to sign off on the validation on stage (VSC will send you instruction on how to do it).

  • You will need to be available at the day and time of the redirection.

  • Content will need to be published for all locales live under the new URLs before the redirection. This is to ensure the target endpoints is live and doesn’t throw non 200 to avoid bad end user experience.
    • If you are renaming the base URL, VSC will do that for you and publish your content live. Note that this change affects all locales.
    • If you are just renaming a folder, content will need to go live before we apply the redirection.


Due to the redirection activation time in production varies, we may expect a very small % of users getting 404s when they try to load the redirecting URLs from their bookmark during the timeframe when the activation is in progress.

How to test site level redirections

Site level redirections might be complicated and it is always safer to test them before they are deployed. This is how to spoof the IP using the offline servers, courtey of Joshua Edvin.

  1. Download and install Fiddler
  2. Open Fiddler and to to the Host file via Tools -> Hosts


  3. Click on Enable remamping of requests from one host to a different host or IP, overriding DNS.

  4. Enter the IP address of the server along with the FQDN of the site and click on save. Here is the information for each of the sites:



  5. Go to the composer tab and paste the test URL. For example, and click enter or execute.


  6. A certificate error might pop up. If so, Click YES.


  7. Observe on the left hand side if the URL has been redirected with a 301


  8. Double click on the URL on the left hand column to see more details on the URL request. You should see the location of the redirect as seen below. Also make sure the X-instance for the msdn URL returns CO105 in the response header. That confirms that you hit the firstoffline machine.