MkDocs Redirects Plugin

1.2.3 · active · verified Sat Apr 11

mkdocs-redirects is a plugin for MkDocs that provides dynamic page redirects, crucial for maintaining link integrity when restructuring documentation. As of version 1.2.3, it offers robust mapping capabilities for internal and external links. The project is under active development, with a recent transition to a new organizational umbrella, ProperDocs, signaling continued evolution.

Warnings

breaking The project maintainers are transitioning to a new organization, ProperDocs, and are encouraging the use of the `properdocs` executable over the traditional `mkdocs` executable. While `mkdocs-redirects` still functions with `mkdocs`, future versions and features may prioritize the ProperDocs ecosystem.
Fix: For long-term compatibility and to align with the project's evolving direction, consider exploring the ProperDocs ecosystem and its `properdocs` executable. Refer to the ProperDocs discussions for more details: `https://github.com/ProperDocs/properdocs/discussions/33`.
breaking Python 3.9 support has been officially dropped.
Fix: Upgrade your Python environment to 3.10 or newer. Python 3.14 is officially supported.
gotcha Paths specified in `redirect_maps` are interpreted relative to your `docs_dir` (e.g., `docs/` by default) for the 'old path' keys. For 'new path' values, absolute paths (starting with `/`) are relative to the site root, and external URLs (starting with `http/https`) are handled directly. Relative paths in values (e.g., `../new-page.md`) are interpreted relative to the source file's location within `docs_dir`.
Fix: Carefully verify redirect paths. For internal redirects, it is often safer and clearer to use absolute paths (e.g., `/new-page/`) for target URLs. Thoroughly test all redirects after configuration changes to prevent broken links.
gotcha If `use_directory_urls` is enabled in your `mkdocs.yml` (which is the default behavior), ensure your redirect target paths in `redirect_maps` reflect the directory-style URL structure (e.g., `new-page/` instead of `new-page.md`). Mixing styles can lead to unexpected redirect behavior.
Fix: Align your redirect target paths with the URL structure generated by MkDocs based on your `use_directory_urls` setting. If `use_directory_urls` is `true`, use directory-style paths for targets; if `false`, use `.html` suffixes.

Install

pip install mkdocs-redirects Install with pip

Imports

```
Not imported directly in Python code. Configured via mkdocs.yml.
```
Users enable and configure this plugin by adding it to the `plugins` section of their MkDocs configuration file, typically `mkdocs.yml`.

Quickstart

To enable `mkdocs-redirects`, add it to the `plugins` section of your `mkdocs.yml` file. Define redirect mappings using `redirect_maps`, where keys are old paths (relative to `docs_dir`) and values are new paths (can be internal relative, absolute, or external URLs).

# mkdocs.yml
site_name: My Awesome Docs

plugins:
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'
        'blog/legacy-post.md': '/blog/current-post/' # Absolute path within site
        'external-link.md': 'https://example.com/new-resource'
        'docs/old-section/chapter-1.md': '../new-section/chapter-1.md' # Relative to docs_dir

view raw JSON →