Redirects

If you use context sensitive help, a challenge is making sure the help links do not break because a target URL changes. This can lock you into topic file names and paths that may not be ideal. Documentation changes, is reorganized, and needs to be flexible. But using context sensitive help or other external sources that rely on a link to your documentation website means you cannot change things.

Material for MkDocs has a redirect feature that allows you to create a pairing of an old topic file and path with the new topic file name and path. This can provide you the flexibility to make changes and allows you to ensure any external links will not end in a 404 page.

The following link goes to a non-existent file named old.md. Copy and paste this link into your browser. The redirect goes to the Features overview.

https://techwords.github.io/features/old

Using Redirects

1. Run the following command to install MkDocs Redirects.

   pip install mkdocs-redirects
   

2. In the mkdocs.yml file, specify your redirects. In the sample below, there is an example for a redirect for files in the same folder, for files in different folders, and a file to a URL.

   plugins:
       - redirects:
           redirect_maps:
               'old.md': 'new.md'
               'old/file.md': 'new/file.md'
               'some_file.md': 'http://external.url.com/foobar'